//----------------------------------------------------------------------------
//
// TSDuck - The MPEG Transport Stream Toolkit
// Copyright (c) 2005-2025, Thierry Lelegard
// BSD-2-Clause license, see LICENSE.txt file or https://tsduck.io/license
//
//----------------------------------------------------------------------------

<<<
=== tstabdump

[.cmd-header]
Dump MPEG tables and sections

This utility dumps in human readable format MPEG tables,
as saved in binary files by the `tstables` utility for instance.

[.usage]
Usage

[source,shell]
----
$ tstabdump [options] [input-file ...]
----

[.usage]
Parameters

[.opt]
_input-file_

[.optdoc]
Binary section file.
Several files can be specified.
By default, without file and without `--ip-udp`, the binary tables are read from the standard input.

[.optdoc]
With `--ip-udp`, no file shall be specified.
Binary sections and tables are received over UDP/IP as sent by the utility `tstables` or the plugin `tables`.

[.usage]
Options

[.opt]
*-x* _value_ +
*--max-tables* _value_

[.optdoc]
Maximum number of tables or sections to dump.
Stop logging tables when this limit is reached.
This option is useful with `--ip-udp` which never ends otherwise.

[.usage]
Tables and sections interpretation and formatting options

[.opt]
*--ignore-crc32*

[.optdoc]
Do not check CRC32 of input sections.
This can be used to analyze sections with incorrect CRC32 but which are otherwise correct.

include::{docdir}/opt/opt-no-pager.adoc[tags=!*]
include::{docdir}/opt/group-section-display.adoc[tags=!*]
include::{docdir}/opt/group-duck-context.adoc[tags=!*;cas;pds;std;timeref;charset]

[.usage]
UDP reception options

These options apply only when `--ip-udp` is used.
In this case, the binary sections are received using UDP/IP.
No input file is used.

[.opt]
*--buffer-size* _value_

[.optdoc]
Specify the UDP socket receive buffer size in bytes (socket option).

[.opt]
*--default-interface*

[.optdoc]
Let the system find the appropriate local interface on which to listen. By default, listen on all
local interfaces.

[.opt]
*--disable-multicast-loop*

[.optdoc]
Disable multicast loopback.

[.optdoc]
By default, incoming multicast packets are looped back on local interfaces, if an application
sends packets to the same group from the same system. This option disables this.

[.optdoc]
*Warning*: On input sockets, this option is effective only on Windows systems.
On {unix}, this option applies only to output sockets.

[.opt]
*--first-source*

[.optdoc]
Filter UDP packets based on the source address.
Use the sender address of the first received packet as only allowed source.

[.optdoc]
This option is useful when several sources send packets to the same destination address and port.
Accepting all packets could result in a corrupted stream and only one sender shall be accepted.

[.optdoc]
To allow a more precise selection of the sender, use option `--source`.
Options `--first-source` and `--source` are mutually exclusive.

[.opt]
*--ip-udp* _[[source@]address:]port_

[.optdoc]
Specify that the sections and tables are received from UDP/IP, as sent by `tstables` or the plugin `tables`.

[.optdoc]
The `_port_` part is mandatory and specifies the UDP port to listen on.
The `_address part_` is optional.
It specifies an IP multicast address to listen on.
It can be also a host name that translates to a multicast address.
If the address is not specified, the plugin simply listens on the specified local port
and receives the packets which are sent to one of the local (unicast) IP addresses of the system.

[.optdoc]
An optional source address can be specified as `_source@address:port_` in the case of source-specific multicast (SSM).

[.opt]
*--local-address* _address_

[.optdoc]
Specify the IP address of the local interface on which to listen.
It can be also a host name that translates to a local address.
By default, listen on all local interfaces.

[.opt]
*--no-encapsulation*

[.optdoc]
With `--ip-udp`, receive the tables as raw binary messages in UDP packets.
By default, the tables are formatted into TLV messages.

[.opt]
*--no-link-local*

[.optdoc]
Do not join multicast groups from link-local addresses, typically 169.254.xx.xx.
These addresses are often auto-configured and may not be allowed to receive multicast, especially on Windows.

[.optdoc]
By default, join multicast groups from all local interfaces.

[.opt]
*--no-reuse-port*

[.optdoc]
Disable the reuse port socket option.
Do not use unless completely necessary.

[.opt]
*--receive-timeout* _value_

[.optdoc]
Specify the UDP reception timeout in milliseconds.
This timeout applies to each receive operation, individually.
By default, receive operations wait for data, possibly forever.

[.opt]
*--reuse-port*

[.optdoc]
Set the reuse port socket option.
This is now enabled by default, the option is present for legacy only.

[.opt]
*--source* _address[:port]_

[.optdoc]
Filter UDP packets based on the specified source address.
This option is useful when several sources send packets to the same destination address and port.
Accepting all packets could result in a corrupted stream and only one sender shall be accepted.

[.optdoc]
Options `--first-source` and `--source` are mutually exclusive.

[.opt]
*--ssm*

[.optdoc]
This option forces the usage of source-specific multicast (SSM)
using the source address which is specified by the option `--source`.
Without `--ssm`, standard ("any-source") multicast is used and the option `--source` is used to filter incoming packets.

[.optdoc]
The `--ssm` option is implicit when the classical SSM syntax `_source@address:port_` is used.

include::{docdir}/opt/group-common-commands.adoc[tags=!*]
