PLUMBER(4)                                             PLUMBER(4)

     NAME
          plumber - file system for interprocess messaging

     SYNOPSIS
          plumber [ -p plumbing ]

     DESCRIPTION
          The plumber is a user-level file server that receives, exam-
          ines, rewrites, and dispatches plumb(6) messages between
          programs.  Its behavior is programmed by a plumbing file
          (default /usr/$user/lib/plumbing) in the format of plumb(6).

          Its services are mounted on the directory /mnt/plumb
          (/mnt/term/mnt/plumb on the CPU server) and consist of two
          pre-defined files, send and rules, and a set of output ports
          for dispatching messages to applications.  The service is
          also published as a srv(4) file, named in $plumbsrv, for
          mounting elsewhere.

          Programs use write (see read(2)) to deliver messages to the
          send file, and read(2) to receive them from the correspond-
          ing port.  For example, sam(1)'s plumb menu item or the B
          command cause a message to be sent to /mnt/plumb/send; sam
          in turn reads from, by convention, /mnt/plumb/edit to
          receive messages about files to open.

          A copy of each message is sent to each client that has the
          corresponding port open.  If none has it open, and the rule
          has a plumb client or plumb start rule, that rule is
          applied.  A plumb client rule causes the specified command
          to be run and the message to be held for delivery when the
          port is opened.  A plumb start rule runs the command but
          discards the message.  If neither start or client is speci-
          fied and the port is not open, the message is discarded and
          a write error is returned to the sender.

          The set of output ports is determined dynamically by the
          specification in the plumbing rules file: a port is created
          for each unique destination of a plumb to rule.

          The set of rules currently active may be examined by reading
          the file /mnt/plumb/rules; appending to this file adds new
          rules to the set, while creating it (opening it with OTRUNC)
          clears the rule set.  Thus the rule set may be edited dynam-
          ically with a traditional text editor.  However, ports are
          never deleted dynamically; if a new set of rules does not
          include a port that was defined in earlier rules, that port
          will still exist (although no new messages will be delivered
          there).

     Page 1                       Plan 9             (printed 3/19/24)

     PLUMBER(4)                                             PLUMBER(4)

     FILES
          /usr/$user/lib/plumbing  default rules file
          /sys/lib/plumb           directory to search for files in
                                   include statements
          /mnt/plumb               mount point for plumber(4).

     SOURCE
          /sys/src/cmd/plumb

     SEE ALSO
          plumb(1), plumb(2), plumb(6)

     BUGS
          Plumber's file name space is fixed, so it is difficult to
          plumb messages that involve files in newly mounted services.

     Page 2                       Plan 9             (printed 3/19/24)