1 files changed, 163 insertions, 0 deletions
diff --git a/man/6/plumbing b/man/6/plumbing
new file mode 100644
index 00000000..d28e26b8
--- /dev/null
+++ b/man/6/plumbing
@@ -0,0 +1,163 @@
+.TH PLUMBING 6
+.SH NAME
+plumbing \- plumbing rules
+.SH DESCRIPTION
+Plumbing rules tell
+.IR plumber (8)
+how to route plumbing messages
+generated by applications using
+.IR plumbmsg (2).
+.PP
+The file is a set of rules separated by blank lines.
+Each
+rule
+is a set of patterns followed by a set of actions.
+The rules are interpreted in order.
+The first rule whose patterns all match is applied, and no further
+rules are examined.
+Comments start with
+.B #
+and continue to end of line.
+Single quotes protect special characters (use
+.B ''
+to get a single quote).
+.PP
+A
+pattern
+has the general form:
+.IP
+.I "field verb arg"
+.PP
+Each
+.I field
+corresponds to a field in the incoming plumbing message:
+.RS
+.TP
+.B src
+Source application
+.TP
+.B dst
+Destination port
+.TP
+.B dir
+Working directory
+.TP
+.B kind
+Format of the data (eg,
+.B text
+or
+.BR image )
+.TP
+.B attr
+A line of
+.IB name = value
+pairs
+.TP
+.B data
+The message data (an array of bytes)
+.RE
+.PP
+The verbs are:
+.RS
+.TF matches
+.PD
+.TP
+.B is
+Exact string comparison with
+.I arg
+.TP
+.B matches
+Regular expression comparison with
+.I arg
+.TP
+.B isdir
+.I Arg
+must name an existing directory
+.TP
+.B isfile
+.I Arg
+must name an existing file
+.TP
+.B set
+Set the value of the
+.I field
+to
+.IR arg .
+This verb operates in place, so put it after all other patterns in the rule.
+.RE
+.PP
+The
+.I arg
+can refer to one of the following variables:
+.RS
+.TF "$0 to $9 "
+.PD
+.TP
+.BR $0 " to " $9
+Substrings resulting from the most recent regular expression match:
+.B $0
+is the entire substring;
+.B $1
+the first parenthesised substring, etc.
+.TP
+.B $file
+The file name examined by the last
+.B isfile
+verb.
+.TP
+.B $dir
+The directory name examined by the last
+.B isdir
+verb.
+.RE
+.PP
+The following actions are provided:
+.RS
+.TP
+.BI "plumb to" " port"
+Route the message to the given plumbing
+.IR port .
+.TP
+.BI "plumb start" " command arg ..."
+If no program is currently listening on the current rule's
+.IR port ,
+start the
+.I command
+with the given arguments.
+The
+.RB ` $ '
+variables listed above can be used, to include part
+of the message in the command line arguments to the program.
+They are replaced in the command string by their actual values.
+.RE
+.PP
+For example, the following rule sends the names of module files\-
+file names ending with suffix
+.RB ` .m '\-
+to
+.IR wm-brutus (1),
+starting it if it is not already running:
+.IP
+.EX
+kind is text
+data matches '([a-zA-Z0-9]+\.m)(:[0-9]+)?'
+data isfile     /module/$1
+data set        /module/$0
+plumb to edit
+plumb start /dis/wm/brutus.dis $file$2
+.EE
+.PP
+Note the use of
+.B $2
+in the
+.B start
+action to pass
+.B brutus
+the line number selected by the second parenthesised
+expression in the pattern.
+.SH FILES
+.BI /usr/ user /lib/plumbing
+.SH SEE ALSO
+.IR plumb (1),
+.IR plumbmsg (2),
+.IR plumber (8)