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