s6: the s6-ioconnect program
Keywords: s6 ioconnect ucspi tcpconnect ipcconnect

s6
Software
skarnet.org

# The `s6-ioconnect` program

`s6-ioconnect` performs full-duplex data transmission between two sets of open file descriptors.

## Interface

         s6-ioconnect [ -t millisecs ] [ -r fdr ] [ -w fdw ]

- s6-ioconnect reads data from its stdin and writes it as is to file descriptor 7, which is assumed to be open.
- It also reads data from its file descriptor 6, which is assumed to be open, and writes it as is to its stdout.
- When both sides have transmitted EOF and s6-ioconnect has flushed its buffers, it exits 0.

## Options

- `-t millisecs` : if no activity on either side happens for millisecs milliseconds, s6-ioconnect closes the connection on both ends and exits 1. By default, millisecs is 0, which means no such timeout.
- `-r fdr` : Use fd fdr for "remote" reading instead of fd 6.
- `-w fdw` : Use fd fdw for "remote" writing instead of fd 7.
- The `-0`, `-1`, `-6` and `-7` options are still recognized for compatibility, but do nothing; they are deprecated. They were previously used to tell s6-ioconnect that the local reading, local writing, remote reading and remote writing endpoints, respectively, were sockets — but this is now autodetected.

## Notes

- The point of s6-ioconnect is to be used together with s6-tcpclient or s6-ipcclient to establish a full- duplex connection between the client and the server, for instance for testing purposes. `s6-ioconnect` is to s6-tcpclient as `cat` is to s6-tcpserver: a program that will just echo what it gets.
- The s6-ioconnect utility was once part of the s6-networking suite, which is why the examples here involve TCP. Nevertheless, it can be used with connections across Unix domain sockets as well, and has its place in the s6 package.
- If one of the endpoints is a socket, s6-ioconnect will call shutdown() on it (for reading or writing, depending on the endpoint) when it needs to transmit EOF. This is a necessary workaround to a misdesign of the socket API, but it could have unintended consequences when the socket is shared among several processes that expect a persistent connection. Most of the time, however, it is a mistake to share a data socket between processes, so s6-ioconnect's behaviour is suited to an overwhelming majority of cases, and the exceptions are specialized enough that they won't need to use s6-ioconnect.