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 ] [ -0 ] [ -1 ] [ -6 ] [ -7 ]

- 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.
- `-0`: assume stdin is a socket and needs to be shut down for reading after an EOF.
- `-1`: assume stdout is a socket and needs to be shut down for writing to correctly transmit an EOF.
- `-6`: assume the remote reading fd is a socket and needs to be shut down for reading after an EOF.
- `-7`: assume the remote writing fd is a socket and needs to be shut down for writing to correctly transmit an EOF.

## Notes

- Transmitting EOF across full-duplex sockets is ugly. The right thing in every case cannot be automatically determined, so it is up to the user to mention that a socket must be shut down. Most of the time, though, shutting down sockets after EOF is the right thing to do, so `s6-ioconnect -67` should be the common use case.
- 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.
- On modern Linux systems, s6-ioconnect will perform zero-copy data transmission, via the splice system call.
- 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.