S6-IOCONNECT(8)

📦 version 2.15.1.0, in nixpkgs unstable

💅 s6-ioconnect(8) — the full-duplex bestie

okay so this is the s6-ioconnect page from the System Manager's Manual, and honestly? it's giving "tiny program, big job" energy ✨

🎀 NAME 🎀

s6-ioconnect — perform full-duplex data transmission between two sets of open file descriptors. yes bestie, both directions at once, we contain multitudes 💖

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

okay so here's the vibe: s6-ioconnect reads data from its stdin and writes it as-is to file descriptor 7, which is assumed to be open. no questions, no formatting, just straight piping 🫶

it also reads data from its file descriptor 6 — also assumed to be open — and writes it as-is to its stdout. yes at the same time. full duplex. main character energy 👑

when both sides have transmitted EOF and s6-ioconnect has flushed its buffers, it exits 0. clean exit, no drama, slay 💅

the whole point of s6-ioconnect is to be used together with s6-tcpclient or s6-ipcclient(8) 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(1) is to s6-tcpserver: a program that will just echo what it gets. literally the cat of networking, iconic 🌈

fun lore drop: the s6-ioconnect utility was once part of the s6-networking suite, which is why the examples here involve TCP. ngl it's just where it grew up. nevertheless, it can be used with connections across Unix domain sockets as well, and has its place in the s6 package 💜

⚠️ okay important part, listen up: if one of the endpoints is a socket, s6-ioconnect will call shutdown(2) on it (for reading or writing, depending on the endpoint) when it needs to transmit EOF. this is a necessary workaround to a misdesign[1] 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. fr fr, read that twice 🍓

✨ 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. set it if you're the impatient type 🙈
  • -r fdr — use fd fdr for “remote” reading instead of fd 6. pick your own adventure 🧚
  • -w fdw — use fd fdw for “remote” writing instead of fd 7. same energy, other direction 💫
💀 heads up: 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. so yeah, they're little ghosts haunting the option parser 👻

🔥 SEE ALSO 🔥

[1] https://cr.yp.to/tcpip/twofd.html — go read it, iykyk 📚

this man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/s6-ioconnect.html

👑 AUTHORS 👑

  • Laurent Bercot
  • Alexis <flexibeast@gmail.com> (man page port)

and that's the page bestie 💖 brought to you by Debian, dated February 19, 2023 — S6-IOCONNECT(8), ported with love, autodetected with grace 🎀✨

📦 where this page comes from