TCPING(1)

NAME
tcping - non-blocking TCP connection test

SYNOPSIS
tcping [-q] [-f <4|6> ] [-t timeout-sec | -u timeout-usec ] host port

DESCRIPTION
tcping attempts to complete a TCP connection to a host:port combination within the time interval timeout-[u]sec. The result of the operation is encoded as a return value.

OPTIONS

-q  Quiet flag. Suppress all informational output.

-f <4|6>
    IP protocol family to use: 4 for IPv4, 6 for IPv6. If left unspecifed, the implementation will use the protocol family of the first record returned from getaddrinfo(3), based on the format of the host parameter. Specifying host as dotted-decimal IPv4 or hex IPv6 address string will use the respective protocol stack. Specification as a hostname character string will cause a dependency on the order of IPv4 and IPv6 records returned from getaddrinfo(3).

-t timeout-sec
    Connection timeout in seconds.

-u timeout-usec
    Connection timeout in microseconds.

host
    Destination host. Either a host name node name or a numeric host address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex address), per RFC 2553.

port
    Destination port. Either a service name or a decimal port number, per RFC 2553.

RETURN VALUES
tcping encodes the result of the connection attempt in its return value:

0   The connection attempt was successful.

1   The connection attempt was unsuccessful.

2   The connection attempt timed out.

255 An error occured.

DIAGNOSTICS
Unless the quiet (-q) flag is set, the following diagnostics are issued on stderr. The messages align with the program return value (see above). <host> port <port> open.
    The connection attempt to host:port was successful.
<host> port <port> closed.
    The connection attempt to host:port was unsuccessful and the server side signaled a closed port.
<host> port <port> user timeout.
    The connection attempt to host:port did not complete within the user-defined timeout interval.

AUTHOR
Marc Kirchner <mail at marc-kirchner dot de>

HISTORY
tcping came to be in 2002 as a utility to allow basic TCP connection checking and to enable failure shortcircutry before issuing network commands with long timeouts (on Solarix 2.x, Solaris 7/8, AIX and Linux). IPv6 functionality was added for 2.0.0 in 2023, which also dropped support for the AIX and Solaris OS.

ACKNOWLEDGEMENTS
Many thanks to Kai Hambrecht, John Smith and Vincent Loriot.

SEE ALSO
nc(1)