s6-networking
Software
skarnet.org

The s6-tcpclient program

s6-tcpclient is an UCSPI client tool for INET domain sockets. It establishes a TCP connection to a server, then executes into a program.

Interface

     s6-tcpclient [ -q | -Q | -v ] [ -4 | -6 ] [ -d | -D ] [ -r | -R ] [ -h ] [ -H ] [ -n | -N ] [ -t timeout ] [ -l localname ] [ -T timeoutconn ] [ -i localip ] [ -p localport ] host port prog...

• s6-tcpclient establishes a TCP connection to host host port port.
• It executes into prog... with descriptor 6 reading from the network and descriptor 7 writing to it.

Host address determination

• host may be an IP address, in which case s6-tcpclient will connect to that IP address. If the underlying skalibs has been compiled with IPv6 support, host can be an IPv6 address as well as an IPv4 one.
• host may be a domain name, in which case a DNS resolution will be performed on it, and a connection will be tried to all the resulting IP addresses in a round-robin fashion, twice: first with a small timeout, then with a longer timeout. The first address to answer wins. The connection attempt fails if no address in the list is able to answer.

Environment variables

prog... is run with the following variables set:

• PROTO: always set to TCP
• TCPREMOTEIP: set to the chosen IP address of host.
• TCPREMOTEPORT: set to port.
• TCPREMOTEHOST: if the -H option has been given, set to the name obtained by a reverse DNS resolution of the IP address chosen for host. Else unset.
• TCPLOCALHOST: if the -l option has been given, set to localname. Else set to the name obtained by a reverse DNS resolution of the IP address chosen for the local host.
• TCPREMOTEINFO: if the -r option has been given, set to the information given by an IDENT server on host about the current connection (very unreliable). Else unset.

Options

• -q : be quiet.
• -Q : be normally verbose. This is the default.
• -v : be verbose.
• -4 : Interpret host as an IPv4 address or make A queries to determine its addresses. Do not attempt IPv6.
• -6 : (only valid if the underlying skalibs has IPv6 support) Interpret host as an IPv6 address or make AAAA queries to determine its addresses. Do not attempt IPv4.
• -d : don't use the TCP_NODELAY socket option. This is the default.
• -D : use the TCP_NODELAY socket option, which disables Nagle's algorithm.
• -r : try and obtain a TCPREMOTEINFO string via the IDENT protocol. This is obsolete and unreliable, and should only be used for compatibility with legacy programs.
• -R : do not use the IDENT protocol. This is the default.
• -h : Consult the /etc/hosts database before performing DNS queries. The default, when this option is not given, is to ignore /etc/hosts. The -H option overrides -h and voids any kind of lookup.
• -H : do not try and obtain the local or remote host names via DNS. The default, when this option is not given, is to look up the local and remote host IPs in the DNS database to get the corresponding names.
• -n : qualify host when resolving it to find suitable IP addresses. This is the default.
• -N : do not qualify host.
• -t :timeout : put a global timeout on the connection attempt. If no fully functional connection has been established after timeout seconds, abort the program. By default, timeout is 0, which means no timeout.
• -i localip : use localip as the local socket address for the connection. By default, address selection is left to the operating system.
• -p localport : use localport as the local socket port for the connection. By default, port selection is left to the operating system.
• -l localname : use localname as the value of the TCPLOCALHOST environment variable instead of looking it up via the DNS.
• -T :timeoutconn : configure the connection timeouts. timeoutconn must be of the form x+y, where x and y are integers. x is the first timeout and y is the second one: all suitable addresses for host are first tried with a timeout of x seconds, and if all of them fail, then they are tried again with a timeout of y seconds. (Be aware that the timeout specified with the -t option overrides everything.) By default, x is 2 and y is 58.