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