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 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 mode	omode.	If port	begins
       with  a	slash, it is taken as a	literal	file name; otherwise plumbopen
       searches	for the	location of the	service	and opens the port there.

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

       The  library mounts the service on demand (using	the 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	recon-
       nect.

       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

       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
       which  masks  information about read and	write errors.  This is accept-
       able for	use in plumbrecv but not for plumbsend,	which depends on  see-
       ing  details  of	 write errors.	Plumbopenfid, plumbrecvfid, and	plumb-
       sendtofid provide an explicit interface to lib9pclient  that  preserves
       the exact error details.

SOURCE
       /src/libplumb

SEE ALSO
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+13.0-RELEASE+and+Ports>

home | help