plumb

PLUMB(3)                    Library Functions Manual                    PLUMB(3)



NAME
       eplumb, plumbfree, plumbopen, plumbunmount, plumbopenfid, plumbsend,
       plumbsendtofid, plumbsendtext, plumblookup, plumbpack, plumbpackattr,
       plumbaddattr, plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack,
       plumbunpackpartial, plumbunpackattr, Plumbmsg  - plumb messages

SYNOPSIS
       #include <u.h>
       #include <libc.h>
       #include <plumb.h>

       int        plumbopen(char *port, int omode)

       int        plumbunmount(void)

       int        plumbsend(int fd, Plumbmsg *m)

       int        plumbsendtext(int fd, char *src, char *dst, char *wdir, char
       *data)

       void       plumbfree(Plumbmsg *m)

       Plumbmsg*  plumbrecv(int fd)

       char*      plumbpack(Plumbmsg *m, int *np)

       Plumbmsg*  plumbunpack(char *buf, int n)

       Plumbmsg*  plumbunpackpartial(char *buf, int n, int *morep)

       char*      plumbpackattr(Plumbattr *a)

       Plumbattr* plumbunpackattr(char *a)

       char*      plumblookup(Plumbattr *a, char *name)

       Plumbattr* plumbaddattr(Plumbattr *a, Plumbattr *new)

       Plumbattr* plumbdelattr(Plumbattra *a, char *name)

       int        eplumb(int key, char *port)

       #include <9pclient.h>

       CFid       *plumbopenfid(char *port, int omode)

       Plumbmsg*  plumbrecvfid(CFid *fid)

       int        plumbsendtofid(CFid *fid, Plumbmsg *m)

DESCRIPTION
       These routines manipulate plumb(7) messages, transmitting them, receiving
       them, and converting them between text and these data structures:

              typedef
              struct Plumbmsg
              {
                    char      *src;
                    char      *dst;
                    char      *wdir;
                    char      *type;
                    Plumbattr *attr;
                    int       ndata;
                    char      *data;
              } Plumbmsg;

              typedef
              struct Plumbattr
              {
                    char      *name;
                    char      *value;
                    Plumbattr *next;
              } Plumbattr;

       Plumbopen opens the named plumb port, using open(3) mode omode.  If port
       begins with a slash, it is taken as a literal file name; otherwise
       plumbopen searches for the location of the plumber(4) service and opens
       the port there.

       For programs using the event(3) interface, eplumb registers, using the
       given key, receipt of messages from the named port.

       The library mounts the plumber(4) service on demand (using the
       9pclient(3)) library and reuses the mount instance for future calls to
       plumbopen.  Plumbunmount causes the library to discard its cached mount.
       This can be useful if the plumber service itself has been restarted and a
       client wishes to reconnect.

       Plumbsend formats and writes message m to the file descriptor fd, which
       will usually be the result of plumbopen("send", OWRITE).  Plumbsendtext
       is a simplified version for text-only messages; it assumes type is text,
       sets attr to nil, and sets ndata to strlen(data).

       Plumbfree frees all the data associated with the message m, all the
       components of which must therefore have been allocated with malloc(3).

       Plumbrecv returns the next message available on the file descriptor fd,
       or nil for error.

       Plumbpack encodes message m as a character string in the format of
       plumb(7), setting *np to the length in bytes of the string.  Plumbunpack
       does the inverse, translating the n bytes of buf into a Plumbmsg.

       Plumbunpackpartial enables unpacking of messages that arrive in pieces.
       The first call to plumbunpackpartial for a given message must be
       sufficient to unpack the header; subsequent calls permit unpacking
       messages with long data sections.  For each call, buf points to the
       beginning of the complete message received so far, and n reports the
       total number of bytes received for that message.  If the message is
       complete, the return value will be as in plumbunpack.  If not, and morep
       is not null, the return value will be nil and *morep will be set to the
       number of bytes remaining to be read for this message to be complete
       (recall that the byte count is in the header).  Those bytes should be
       read by the caller, placed at location buf+n, and the message unpacked
       again.  If an error is encountered, the return value will be nil and
       *morep will be zero.

       Plumbpackattr converts the list a of Plumbattr structures into a null-
       terminated string.  If an attribute value contains white space, quote
       characters, or equal signs, the value will be quoted appropriately.  A
       newline character will terminate processing.  Plumbunpackattr converts
       the null-terminated string a back into a list of Plumbattr structures.

       Plumblookup searches the Plumbattr list a for an attribute with the given
       name and returns the associated value.  The returned string is the
       original value, not a copy.  If the attribute has no value, the returned
       value will be the empty string; if the attribute does not occur in the
       list at all, the value will be nil.

       Plumbaddattr appends the new Plumbattr (which may be a list) to the
       attribute list a and returns the new list.  Plumbattr searches the list a
       for the first attribute with name name and deletes it from the list,
       returning the resulting list.  Plumbdelattr is a no-op if no such
       attribute exists.

       The file descriptor returned by plumbopen is created with fsopenfd (see
       9pclient(3)), which masks information about read and write errors.  This
       is acceptable for use in plumbrecv but not for plumbsend, which depends
       on seeing details of write errors.  Plumbopenfid, plumbrecvfid, and
       plumbsendtofid provide an explicit interface to lib9pclient that
       preserves the exact error details.

SOURCE
       /src/libplumb

SEE ALSO
       plumb(1), event(3), plumber(4), plumb(7)

DIAGNOSTICS
       When appropriate, including when a plumbsend fails, these routine set
       errstr.

BUGS
       To avoid rewriting clients that use plumbsend, the call plumbopen("send",
       OWRITE) returns a useless file descriptor (it is opened to /dev/null).
       Plumbsend looks for this particular file descriptor and uses a static
       copy of the CFid instead.



                                                                        PLUMB(3)