Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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, receiv-
       ing 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.   Plumbun-
       pack 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	suffi-
       cient  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  re-
       turn  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 re-
       turned 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 at-
       tribute 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  at-
       tribute 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
       /usr/local/plan9/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 de-
       scriptor	and uses a static copy of the CFid instead.

								      PLUMB(3)

NAME | SYNOPSIS | DESCRIPTION | SOURCE | SEE ALSO | DIAGNOSTICS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=plumb&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help