INTRO(4)

💅 INTRO(4) — introduction to file servers 💅

okay so welcome to the Kernel Interfaces Manual, bestie — this is INTRO(4), and it's literally the intro to file servers. Buckle up, it's giving “Plan 9 lore but make it make sense.” 🦋

🌸 NAME 🌸

intro — introduction to file servers ✨

💖 DESCRIPTION 💖

Plan 9 file servers are all about handing processes a file tree — that's the whole vibe. The servers described in this manual section are ones you can mount in a name space, so some interesting service shows up with a file-like interface. A server can be a conventional file system provider — files maintained on permanent storage — or a process that synthesizes files in some manner. Both flavors, both valid. 💅

In Plan 9, the kernel mount device mnt(3) is the client for the 9P servers mounted in the current name space. It translates system calls such as open(2) into 9P transactions such as open(9p) — yes, the kernel is doing the translation, iconic. The kernel also multiplexes the potentially many processes onto a single 9P conversation with each server. And each process gets its own private name space, which it can customize at will. Modern Unix systems do not provide these niceties, so the Unix port of these Plan 9 file servers provides them via other means. 🫶

On Unix, 9P clients do not access servers via the traditional file system call interface — that doorway only reaches the Unix name space. Instead, 9P clients use the 9pclient(3) library to connect and interact directly with particular 9P servers. The 9p(1) command-line client is useful for interactive use and in shell scripts. iykyk. ✨

9P servers call 9pserve(4) — usually through post9pservice(3) — so the façade of a single 9P conversation with each server stays intact. 9pserve announces a 9P service at a particular network address and multiplexes the clients that connect to that address onto a single 9P conversation with the server. It's giving “one conversation, many clients,” and honestly? Obsessed. 🫶

A ported program lives in a pseudo-name space that determines which 9P servers it is using. The name space is represented by a directory containing Unix domain sockets, one for each 9P server. By default that directory is /tmp/ns.$USER.$DISPLAY, meaning that all programs in an X Windows login session share a single name space. Setting the $NAMESPACE environment variable overrides this default. The namespace(1) command prints the current name space directory. Cute, right? 🎀

Sometimes you want to connect the input or output of a standard Unix program to a file served by a 9P server. The new openfd(9p) 9P transaction depends on file descriptor passing and provides a sufficient workaround in many cases. 9pserve's implementation of openfd (see also fsopenfd in 9pclient(3)) returns the read or write end of a pipe; a helper process transfers data between the other end of the pipe and the 9P server. Heads up: since the data is being transferred via a pipe, 9P read and write errors cannot be passed on to the Unix program. The Unix program sees only end-of-file or a closed pipe. That's the catch, bestie — no 9P read/write error gossip gets through. 💀

That's the whole page! Source/version: INTRO(4) from the Kernel Interfaces Manual. Date: not printed in the original footer — it's just INTRO(4) again, so no invented date, periodt. Stay iconic, stay mounted. 💖✨