<head>
<title>plumb(7) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>PLUMB(7)</b><td align=right><b>PLUMB(7)</b>
<tr><td width=20><td colspan=2>
    <br>
<p><font size=+1><b>NAME     </b></font><br>

<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

    plumb &ndash; format of plumb messages and rules<br>
    
</table>
<p><font size=+1><b>SYNOPSIS     </b></font><br>

<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

    <tt><font size=+1>#include &lt;plumb.h&gt;<br>
    </font></tt>
</table>
<p><font size=+1><b>DESCRIPTION     </b></font><br>

<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

    <p><font size=+1><b>Message format     </b></font><br>
    The messages formed by the <a href="../man3/plumb.html"><i>plumb</i>(3)</a> library are formatted for
    transmission between processes into textual form, using newlines
    to separate the fields. Only the data field may contain embedded
    newlines. The fields occur in a specified order, and each has
    a name, corresponding to the elements of the <tt><font size=+1>Plumbmsg
    </font></tt>structure, that is used in the plumbing rules. The fields, in
    order, are:<br>
    
    <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

        <tt><font size=+1>src</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;application/service generating message<br>
        <tt><font size=+1>dst</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;destination &#8216;port&#8217; for message<br>
        <tt><font size=+1>wdir</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;working directory (used if data is a file name)<br>
        <tt><font size=+1>type</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;form of the data, e.g. <tt><font size=+1>text<br>
        attr</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;attributes of the message, in <i>name</i><tt><font size=+1>=</font></tt><i>value</i> pairs separated by
        white space (the value must follow the usual quoting convention
        if it contains white space or quote characters or equal signs;
        it cannot contain a newline)<br>
        <tt><font size=+1>ndata</font></tt>&nbsp;&nbsp;&nbsp;number of bytes of data<br>
        <tt><font size=+1>data</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;the data itself<br>
        
    </table>
    At the moment, only textual data (<tt><font size=+1>type=text</font></tt>) is supported. 
    <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    
    All fields are optional, but <tt><font size=+1>type</font></tt> should usually be set since
    it describes the form of the data, and <tt><font size=+1>ndata</font></tt> must be an accurate
    count (possibly zero) of the number of bytes of data. A missing
    field is represented by an empty line.<br>
    <p><font size=+1><b>Plumbing rules     </b></font><br>
    The <tt><font size=+1>plumber</font></tt> (see <a href="../man1/plumb.html"><i>plumb</i>(1)</a>) receives messages on its <tt><font size=+1>send</font></tt> port
    (applications <i>send</i> messages there), interprets and reformats them,
    and (typically) emits them from a destination port. Its behavior
    is determined by a plumbing rules file, default <tt><font size=+1>/usr/$user/lib/plumbing</font></tt>,
    which defines a set of pattern/action
    rules with which to analyze, rewrite, and dispatch received messages.
    
    <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    
    The file is a sequence of rule sets, each of which is a set of
    one-line rules called patterns and actions. There must be at least
    one pattern and one action in each rule set. (The only exception
    is that a rule set may contain nothing but <tt><font size=+1>plumb to</font></tt> rules; such
    a rule set declares the named ports but has no other effect.)
    A
    blank line terminates a rule set. Lines beginning with a <tt><font size=+1>#</font></tt> character
    are commentary and are regarded as blank lines. 
    <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    
    A line of the form<br>
    
    <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

        <tt><font size=+1>include</font></tt> <i>file<br>
        </i>
    </table>
    substitutes the contents of <i>file</i> for the line, much as in a C
    <tt><font size=+1>#include</font></tt> statement. Unlike in C, the file name is not quoted.
    If <i>file</i> is not an absolute path name, or one beginning <tt><font size=+1>./</font></tt> or <tt><font size=+1>../</font></tt>,
    <i>file</i> is looked for first in the directory in which the plumber
    is executing, and then in <tt><font size=+1>/sys/lib/plumb</font></tt>. 
    <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    
    When a message is received by the <tt><font size=+1>plumber</font></tt>, the rule sets are examined
    in order. For each rule set, if the message matches all the patterns
    in the rule set, the actions associated with the rule set are
    triggered to dispose of the message. If a rule set is triggered,
    the rest are ignored for this message. If none is
    triggered, the message is discarded (giving a write error to the
    sender) unless it has a <tt><font size=+1>dst</font></tt> field that specifies an existing port,
    in which case the message is emitted, unchanged, from there. 
    <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    
    Patterns and actions all consist of three components: an <i>object</i>,
    a <i>verb</i>, and arguments. These are separated by white space on the
    line. The arguments may contain quoted strings and variable substitutions,
    described below, and in some cases contain multiple words. The
    object and verb are single words from a pre-
    defined set. 
    <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    
    The object in a pattern is the name of an element of the message,
    such as <tt><font size=+1>src</font></tt> or <tt><font size=+1>data</font></tt>, or the special case <tt><font size=+1>arg</font></tt>, which refers to
    the argument component of the current rule. The object in an action
    is always the word <tt><font size=+1>plumb</font></tt>. 
    <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    
    The verbs in the pattern rules describe how the objects and arguments
    are to be interpreted. Within a rule set, the patterns are evaluated
    in sequence; if one fails, the rule set fails. Some verbs are
    predicates that check properties of the message; others rewrite
    components of the message and implicitly always succeed.
    Such rewritings are permanent, so rules that specify them should
    be placed after all pattern-matching rules in the rule set.<br>
    
    <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

        <tt><font size=+1>add</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The object must be <tt><font size=+1>attr</font></tt>. Append the argument, which must be
        a sequence of <i>name</i><tt><font size=+1>=</font></tt><i>value</i> pairs, to the list of attributes of the
        message.<br>
        <tt><font size=+1>delete</font></tt>&nbsp;&nbsp;&nbsp;The object must be <tt><font size=+1>attr</font></tt>. If the message has an attribute
        whose name is the argument, delete it from the list of attributes
        of the message. (Even if the message does not, the rule matches
        the message.)<br>
        <tt><font size=+1>is</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;If the text of the object is identical to the text of the argument,
        the rule matches.<br>
        <tt><font size=+1>isdir</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;If the text of the object is the name of an existing directory,
        the rule matches and sets the variable <tt><font size=+1>$dir</font></tt> to that directory
        name.<br>
        <tt><font size=+1>isfile</font></tt>&nbsp;&nbsp;&nbsp;If the text of the object is the name of an existing file
        (not a directory), the rule matches and sets the variable <tt><font size=+1>$file</font></tt>
        to that file name.<br>
        <tt><font size=+1>matches</font></tt>If the entire text of the object matches the regular expression
        specified in the argument, the rule matches. This verb is described
        in more detail below.<br>
        <tt><font size=+1>set</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The value of the object is set to the value of the argument.<br>
        
        <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
        
        
    </table>
    The <tt><font size=+1>matches</font></tt> verb has special properties that enable the rules
    to select which portion of the data is to be sent to the destination.
    By default, a <tt><font size=+1>data matches</font></tt> rule requires that the entire text
    matches the regular expression. If, however, the message has an
    attribute named <tt><font size=+1>click</font></tt>, that reports that the message was
    produced by a mouse click within the text and that the regular
    expressions in the rule set should be used to identify what portion
    of the data the user intended. Typically, a program such as an
    editor will send a white-space delimited block of text containing
    the mouse click, using the value of the <tt><font size=+1>click</font></tt> attribute (a
    number starting from 0) to indicate where in the textual data
    the user pointed. 
    <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    
    When the message has a <tt><font size=+1>click</font></tt> attribute, the <tt><font size=+1>data matches</font></tt> rules
    extract the longest leftmost match to the regular expression that
    contains or abuts the textual location identified by the <tt><font size=+1>click</font></tt>.
    For a sequence of such rules within a given rule set, each regular
    expression, evaluated by this specification, must
    match the same subset of the data for the rule set to match the
    message. For example, here is a pair of patterns that identify
    a message whose data contains the name of an existing file with
    a conventional ending for an encoded picture file:<br>
    
    <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

        <tt><font size=+1>data matches '[a&#8722;zA&#8722;Z0&#8722;9_&ndash;./]+'<br>
        data matches '([a&#8722;zA&#8722;Z0&#8722;9_&ndash;./]+).(jpe?g|gif|bit|ps|pdf)'<br>
        </font></tt>
    </table>
    The first expression extracts the largest subset of the data around
    the click that contains file name characters; the second sees
    if it ends with, for example, <tt><font size=+1>.jpeg</font></tt>. If only the second pattern
    were present, a piece of text <tt><font size=+1>horse.gift</font></tt> could be misinterpreted
    as an image file named <tt><font size=+1>horse.gif</font></tt>. 
    <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    
    If a <tt><font size=+1>click</font></tt> attribute is specified in a message, it will be deleted
    by the <tt><font size=+1>plumber</font></tt> before sending the message if the <tt><font size=+1>data matches</font></tt>
    rules expand the selection. 
    <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    
    The action rules all have the object <tt><font size=+1>plumb</font></tt>. There are only three
    verbs for action rules:<br>
    
    <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

        <tt><font size=+1>to</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The argument is the name of the port to which the message will
        be sent. If the message has a destination specified, it must match
        the <tt><font size=+1>to</font></tt> port of the rule set or the entire rule set will be skipped.
        (This is the only rule that is evaluated out of order.)<br>
        <tt><font size=+1>client</font></tt>&nbsp;&nbsp;&nbsp;If no application has the port open, the arguments to a
        <tt><font size=+1>plumb start</font></tt> rule specify a shell program to run in response to
        the message. The message will be held, with the supposition that
        the program will eventually open the port to retrieve it.<br>
        <tt><font size=+1>start</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;Like <tt><font size=+1>client</font></tt>, but the message is discarded. Only one <tt><font size=+1>start</font></tt>
        or <tt><font size=+1>client</font></tt> rule should be specified in a rule set.<br>
        
        <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
        
        
    </table>
    The arguments to all rules may contain quoted strings, exactly
    as in <a href="../man1/rc.html"><i>rc</i>(1)</a>. They may also contain simple string variables, identified
    by a leading dollar sign <tt><font size=+1>$</font></tt>. Variables may be set, between rule
    sets, by assignment statements in the style of <tt><font size=+1>rc</font></tt>. Only one variable
    assignment may appear on a line. The <tt><font size=+1>plumber</font></tt> also
    maintains some built-in variables:<br>
    
    <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

        <tt><font size=+1>$0</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The text that matched the entire regular expression in a previous
        <tt><font size=+1>data matches</font></tt> rule. <tt><font size=+1>$1</font></tt>, <tt><font size=+1>$2</font></tt>, etc. refer to text matching the first,
        second, etc. parenthesized subexpression.<br>
        <tt><font size=+1>$attr</font></tt>&nbsp;&nbsp;&nbsp;The textual representation of the attributes of the message.<br>
        <tt><font size=+1>$data</font></tt>&nbsp;&nbsp;&nbsp;The contents of the data field of the message.<br>
        <tt><font size=+1>$dir</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;The directory name resulting from a successful <tt><font size=+1>isdir</font></tt> rule.
        If no such rule has been applied, it is the string constructed
        syntactically by interpreting <tt><font size=+1>data</font></tt> as a file name in <tt><font size=+1>wdir</font></tt>.<br>
        <tt><font size=+1>$dst</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;The contents of the <tt><font size=+1>dst</font></tt> field of the message.<br>
        <tt><font size=+1>$file</font></tt>&nbsp;&nbsp;&nbsp;The file name resulting from a successful <tt><font size=+1>isfile</font></tt> rule. If
        no such rule has been applied, it is the string constructed syntactically
        by interpreting <tt><font size=+1>data</font></tt> as a file name in <tt><font size=+1>wdir</font></tt>.<br>
        <tt><font size=+1>$type</font></tt>&nbsp;&nbsp;&nbsp;The contents of the <tt><font size=+1>type</font></tt> field of the message.<br>
        <tt><font size=+1>$src</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;The contents of the <tt><font size=+1>src</font></tt> field of the message.<br>
        <tt><font size=+1>$wdir</font></tt>&nbsp;&nbsp;&nbsp;The contents of the <tt><font size=+1>wdir</font></tt> field of the message.<br>
        <tt><font size=+1>$plan9</font></tt>The root directory of the Plan 9 tree (see <a href="../man3/get9root.html"><i>get9root</i>(3)</a>).<br>
        
    </table>
    
</table>
<p><font size=+1><b>EXAMPLE     </b></font><br>

<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

    The following is a modest, representative file of plumbing rules.<br>
    <tt><font size=+1># these are generally in order from most specific to least,<br>
    # since first rule that fires wins.<br>
    addr=':(#?[0&#8722;9]+)'<br>
    protocol='(https?|ftp|file|gopher|mailto|news|nntp|telnet|wais)'<br>
    domain='[a&#8722;zA&#8722;Z0&#8722;9_@]+([.:][a&#8722;zA&#8722;Z0&#8722;9_@]+)*/?[a&#8722;zA&#8722;Z0&#8722;9_?,%#~&amp;/\&#8722;]+'<br>
    file='([:.][a&#8722;zA&#8722;Z0&#8722;9_?,%#~&amp;/\&#8722;]+)*'<br>
    # image files go to page<br>
    type is text<br>
    data matches '[a&#8722;zA&#8722;Z0&#8722;9_\&#8722;./]+'<br>
    data matches '([a&#8722;zA&#8722;Z0&#8722;9_\&#8722;./]+).(jpe?g|gif|bit)'<br>
    arg isfile $0<br>
    plumb to image<br>
    plumb start page &#8722;w $file<br>
    # URLs go to web browser<br>
    type is text<br>
    data matches $protocol://$domain$file<br>
    plumb to web<br>
    plumb start window webbrowser $0<br>
    # existing files, possibly tagged by line number, go to edit/sam<br>
    type is text<br>
    data matches '([.a&#8722;zA&#8722;Z0&#8722;9_/&ndash;]+[a&#8722;zA&#8722;Z0&#8722;9_/\&#8722;])('$addr')?'<br>
    arg isfile $1<br>
    data set $file<br>
    attr add addr=$3<br>
    plumb to edit<br>
    plumb start window sam $file<br>
    # .h files are looked up in /sys/include and passed to edit/sam<br>
    type is text<br>
    data matches '([a&#8722;zA&#8722;Z0&#8722;9]+\.h)('$addr')?'<br>
    arg isfile /sys/include/$1<br>
    data set $file<br>
    attr add addr=$3<br>
    plumb to edit<br>
    plumb start window sam $file<br>
    
    <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    </font></tt>
    The following simple plumbing rules file is a good beginning set
    of rules.<br>
    <tt><font size=+1># to update: cp /usr/$user/lib/plumbing /mnt/plumb/rules<br>
    editor = acme<br>
    # or editor = sam<br>
    include basic<br>
    </font></tt>
</table>
<p><font size=+1><b>FILES     </b></font><br>

<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

    <tt><font size=+1>$HOME/lib/plumbing</font></tt>&nbsp;&nbsp;&nbsp;default rules file.<br>
    <tt><font size=+1>plumb</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;service name for <a href="../man4/plumber.html"><i>plumber</i>(4)</a>.<br>
    <tt><font size=+1>/usr/local/plan9/plumb<br>
    </font></tt>
    <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

        
        <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

            directory for <tt><font size=+1>include</font></tt> files.<br>
            
        </table>
        
    </table>
    <tt><font size=+1>/usr/local/plan9/plumb/fileaddr<br>
    </font></tt>
    <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

        
        <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

            public macro definitions.<br>
            
        </table>
        
    </table>
    <tt><font size=+1>/usr/local/plan9/plumb/basic<br>
    </font></tt>
    <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

        
        <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

            basic rule set.<br>
            
        </table>
        
    </table>
    
</table>
<p><font size=+1><b>SEE ALSO     </b></font><br>

<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>

    <a href="../man1/plumb.html"><i>plumb</i>(1)</a>, <a href="../man3/plumb.html"><i>plumb</i>(3)</a>, <a href="../man4/plumber.html"><i>plumber</i>(4)</a>, <a href="../man7/regexp.html"><i>regexp</i>(7)</a><br>
    
</table>

<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>