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