1 files changed, 126 insertions, 0 deletions
diff --git a/static/plan9-4e/man4/plumber.4 b/static/plan9-4e/man4/plumber.4
new file mode 100644
index 00000000..fbaebe41
--- /dev/null
+++ b/static/plan9-4e/man4/plumber.4
@@ -0,0 +1,126 @@
+.TH PLUMBER 4
+.SH NAME
+plumber \- file system for interprocess messaging
+.SH SYNOPSIS
+.B plumber
+[
+.B -p
+.I plumbing
+]
+.SH DESCRIPTION
+The
+.I plumber
+is a user-level file server that receives, examines, rewrites, and dispatches
+.IR plumb (6)
+messages between programs.
+Its behavior is programmed by a
+.I plumbing
+file (default
+.BR /usr/$user/lib/plumbing )
+in the format of
+.IR plumb (6).
+.PP
+Its services are mounted on the directory
+.B /mnt/plumb
+.RB ( /mnt/term/mnt/plumb
+on the CPU server) and consist of two
+pre-defined files,
+.B send
+and
+.BR rules ,
+and a set of output
+.I ports
+for dispatching messages to applications.
+The service is also published as a
+.IR srv (4)
+file, named in
+.BR $plumbsrv ,
+for mounting elsewhere.
+.PP
+Programs use
+.B write
+(see
+.IR read (2))
+to deliver messages to the
+.B send
+file, and
+.IR read (2)
+to receive them from the corresponding port.
+For example,
+.IR sam (1)'s
+.B plumb
+menu item or the
+.B B
+command cause a message to be sent to
+.BR /mnt/plumb/send ;
+.B sam
+in turn reads from, by convention,
+.B /mnt/plumb/edit
+to receive messages about files to open.
+.PP
+A copy of each message is sent to each client that has the corresponding port open.
+If none has it open, and the rule has a
+.B plumb
+.B client
+or
+.B plumb
+.B start
+rule, that rule is applied.
+A
+.B plumb
+.B client
+rule causes the specified command to be run
+and the message to be held for delivery when the port is opened.
+A
+.B plumb
+.B start
+rule runs the command but discards the message.
+If neither
+.B start
+or
+.B client
+is specified and the port is not open,
+the message is discarded and a write error is returned to the sender.
+.PP
+The set of output ports is determined dynamically by the
+specification in the plumbing rules file: a port is created for each unique
+destination of a
+.B plumb
+.B to
+rule.
+.PP
+The set of rules currently active may be examined by reading the file
+.BR /mnt/plumb/rules ;
+appending to this file adds new rules to the set, while
+creating it (opening it with
+.BR OTRUNC )
+clears the rule set.
+Thus the rule set may be edited dynamically with a traditional text editor.
+However, ports are never deleted dynamically; if a new set of rules does not
+include a port that was defined in earlier rules, that port will still exist (although
+no new messages will be delivered there).
+.SH FILES
+.TF /usr/$user/lib/plumbing
+.TP
+.B /usr/$user/lib/plumbing
+default rules file
+.TP
+.B /sys/lib/plumb
+directory to search for files in
+.B include
+statements
+.TP
+.B /mnt/plumb
+mount point for
+.IR plumber (4).
+.SH SOURCE
+.B /sys/src/cmd/plumb
+.SH "SEE ALSO"
+.IR plumb (1),
+.IR plumb (2),
+.IR plumb (6)
+.SH BUGS
+.IR Plumber 's
+file name space is fixed, so it is difficult to plumb
+messages that involve files in newly mounted services.
+