Subversion Repositories planix.SVN

Rev

Rev 2 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 - 1 
.TH PLUMBER 4
2 
.SH NAME
3 
plumber \- file system for interprocess messaging
4 
.SH SYNOPSIS
5 
.B plumber
6 
[
7 
.B -p
8 
.I plumbing
9 
]
10 
.SH DESCRIPTION
11 
The
12 
.I plumber
13 
is a user-level file server that receives, examines, rewrites, and dispatches
14 
.IR plumb (6)
15 
messages between programs.
16 
Its behavior is programmed by a
17 
.I plumbing
18 
file (default
19 
.BR /usr/$user/lib/plumbing )
20 
in the format of
21 
.IR plumb (6).
22 
.PP
23 
Its services are mounted on the directory
24 
.B /mnt/plumb
25 
.RB ( /mnt/term/mnt/plumb
26 
on the CPU server) and consist of two
27 
pre-defined files,
28 
.B send
29 
and
30 
.BR rules ,
31 
and a set of output
32 
.I ports
33 
for dispatching messages to applications.
34 
The service is also published as a
35 
.IR srv (4)
36 
file, named in
37 
.BR $plumbsrv ,
38 
for mounting elsewhere.
39 
.PP
40 
Programs use
41 
.B write
42 
(see
43 
.IR read (2))
44 
to deliver messages to the
45 
.B send
46 
file, and
47 
.IR read (2)
48 
to receive them from the corresponding port.
49 
For example,
50 
.IR sam (1)'s
51 
.B plumb
52 
menu item or the
53 
.B B
54 
command cause a message to be sent to
55 
.BR /mnt/plumb/send ;
56 
.B sam
57 
in turn reads from, by convention,
58 
.B /mnt/plumb/edit
59 
to receive messages about files to open.
60 
.PP
61 
A copy of each message is sent to each client that has the corresponding port open.
62 
If none has it open, and the rule has a
63 
.B plumb
64 
.B client
65 
or
66 
.B plumb
67 
.B start
68 
rule, that rule is applied.
69 
A
70 
.B plumb
71 
.B client
72 
rule causes the specified command to be run
73 
and the message to be held for delivery when the port is opened.
74 
A
75 
.B plumb
76 
.B start
77 
rule runs the command but discards the message.
78 
If neither
79 
.B start
80 
or
81 
.B client
82 
is specified and the port is not open,
83 
the message is discarded and a write error is returned to the sender.
84 
.PP
85 
The set of output ports is determined dynamically by the
86 
specification in the plumbing rules file: a port is created for each unique
87 
destination of a
88 
.B plumb
89 
.B to
90 
rule.
91 
.PP
92 
The set of rules currently active may be examined by reading the file
93 
.BR /mnt/plumb/rules ;
94 
appending to this file adds new rules to the set, while
95 
creating it (opening it with
96 
.BR OTRUNC )
97 
clears the rule set.
98 
Thus the rule set may be edited dynamically with a traditional text editor.
99 
However, ports are never deleted dynamically; if a new set of rules does not
100 
include a port that was defined in earlier rules, that port will still exist (although
101 
no new messages will be delivered there).
102 
.SH FILES
103 
.TF /usr/$user/lib/plumbing
104 
.TP
105 
.B /usr/$user/lib/plumbing
106 
default rules file
107 
.TP
108 
.B /sys/lib/plumb
109 
directory to search for files in
110 
.B include
111 
statements
112 
.TP
113 
.B /mnt/plumb
114 
mount point for
115 
.IR plumber (4).
116 
.SH SOURCE
117 
.B /sys/src/cmd/plumb
118 
.SH "SEE ALSO"
119 
.IR plumb (1),
120 
.IR plumb (2),
121 
.IR plumb (6)
122 
.SH BUGS
123 
.IR Plumber 's
124 
file name space is fixed, so it is difficult to plumb
125 
messages that involve files in newly mounted services.
126