e279699344
Plumber both posts a service to /srv and sets a $plumbsrv environment variable. Our libplumb no longer uses $plumbsrv and nothing else does. It's a silly hack; rc doesn't update /env immediately, and scripts, which for instance set up subrios, cannot rely on it to clean up the plumber at the end. Instead, add the option to specify a srvname, actually check for some common errors and print a usage string. Thanks to Ori for input and a preliminary patch.
135 lines
2.8 KiB
Text
135 lines
2.8 KiB
Text
.TH PLUMBER 4
|
|
.SH NAME
|
|
plumber \- file system for interprocess messaging
|
|
.SH SYNOPSIS
|
|
.B plumber
|
|
[
|
|
.B -p
|
|
.I plumbing
|
|
] [
|
|
.B -s
|
|
.I srvname
|
|
]
|
|
.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.
|
|
.PP
|
|
The service is also published as a
|
|
.IR srv (4)
|
|
file,
|
|
.IR srvname ,
|
|
for mounting elsewhere.
|
|
By default, its name is a dot-separated concatenation
|
|
of the program's name and a process id.
|
|
A different one can be specified via the
|
|
.B -s
|
|
option.
|
|
.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.
|
|
|