sys/man/4/plumber

   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