term% cat index.txt PLUMB(2) System Calls Manual PLUMB(2)
NAME
eplumb, plumbfree, plumbopen, plumbsend, plumbsendtext, plumblookup,
plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv,
plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg - plumb
messages
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <plumb.h>
int plumbopen(char *port, int omode)
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)
DESCRIPTION
These routines manipulate plumb(6) 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(2) 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(2) interface, eplumb registers, using the
given key, receipt of messages from the named port.
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(2).
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(6), 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.
SOURCE
/sys/src/libplumb
SEE ALSO
plumb(1), event(2), plumber(4), plumb(6)
DIAGNOSTICS
When appropriate, including when a plumbsend fails, these routine set
errstr.
PLUMB(2)