240 lines
4.7 KiB
Text
240 lines
4.7 KiB
Text
.TH PLUMB 2
|
|
.SH NAME
|
|
eplumb, plumbfree, plumbopen, plumbsend, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg \- plumb messages
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.br
|
|
.B #include <plumb.h>
|
|
.PP
|
|
.ta \w'\fLPlumbattr* 'u
|
|
.PP
|
|
.B
|
|
int plumbopen(char *port, int omode)
|
|
.PP
|
|
.B
|
|
int plumbsend(int fd, Plumbmsg *m)
|
|
.PP
|
|
.B
|
|
int plumbsendtext(int fd, char *src, char *dst, char *wdir, char *data)
|
|
.PP
|
|
.B
|
|
void plumbfree(Plumbmsg *m)
|
|
.PP
|
|
.B
|
|
Plumbmsg* plumbrecv(int fd)
|
|
.PP
|
|
.B
|
|
char* plumbpack(Plumbmsg *m, int *np)
|
|
.PP
|
|
.B
|
|
Plumbmsg* plumbunpack(char *buf, int n)
|
|
.PP
|
|
.B
|
|
Plumbmsg* plumbunpackpartial(char *buf, int n, int *morep)
|
|
.PP
|
|
.B
|
|
char* plumbpackattr(Plumbattr *a)
|
|
.PP
|
|
.B
|
|
Plumbattr* plumbunpackattr(char *a)
|
|
.PP
|
|
.B
|
|
char* plumblookup(Plumbattr *a, char *name)
|
|
.PP
|
|
.B
|
|
Plumbattr* plumbaddattr(Plumbattr *a, Plumbattr *new)
|
|
.PP
|
|
.B
|
|
Plumbattr* plumbdelattr(Plumbattr *a, char *name)
|
|
.PP
|
|
.B
|
|
int eplumb(int key, char *port)
|
|
.SH DESCRIPTION
|
|
These routines manipulate
|
|
.IR plumb (6)
|
|
messages, transmitting them, receiving them, and
|
|
converting them between text and these data structures:
|
|
.IP
|
|
.EX
|
|
.ta 6n +\w'\fLPlumbattr 'u +\w'ndata; 'u
|
|
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;
|
|
.EE
|
|
.PP
|
|
.I Plumbopen
|
|
opens the named plumb
|
|
.IR port ,
|
|
using
|
|
.IR open (2)
|
|
mode
|
|
.IR omode .
|
|
If
|
|
.I port
|
|
begins with a slash, it is taken as a literal file name;
|
|
otherwise
|
|
.I plumbopen
|
|
searches for the location of the
|
|
.IR plumber (4)
|
|
service and opens the port there.
|
|
.PP
|
|
For programs using the
|
|
.IR event (2)
|
|
interface,
|
|
.I eplumb
|
|
registers, using the given
|
|
.IR key ,
|
|
receipt of messages from the named
|
|
.IR port .
|
|
.PP
|
|
.I Plumbsend
|
|
formats and writes message
|
|
.I m
|
|
to the file descriptor
|
|
.IR fd ,
|
|
which will usually be the result of
|
|
.B plumbopen("send",
|
|
.BR OWRITE) .
|
|
.I Plumbsendtext
|
|
is a simplified version for text-only messages; it assumes
|
|
.B type
|
|
is
|
|
.BR text ,
|
|
sets
|
|
.B attr
|
|
to nil,
|
|
and sets
|
|
.B ndata
|
|
to
|
|
.BI strlen( data )\f1.
|
|
.PP
|
|
.I Plumbfree
|
|
frees all the data associated with the message
|
|
.IR m ,
|
|
all the components of which must therefore have been allocated with
|
|
.IR malloc (2).
|
|
.PP
|
|
.I Plumbrecv
|
|
returns the next message available on the file descriptor
|
|
.IR fd ,
|
|
or nil for error.
|
|
.PP
|
|
.I Plumbpack
|
|
encodes message
|
|
.I m
|
|
as a character string in the format of
|
|
.IR plumb (6) ,
|
|
setting
|
|
.BI * np
|
|
to the length in bytes of the string.
|
|
.I Plumbunpack
|
|
does the inverse, translating the
|
|
.I n
|
|
bytes of
|
|
.I buf
|
|
into a
|
|
.BR Plumbmsg .
|
|
.PP
|
|
.I Plumbunpackpartial
|
|
enables unpacking of messages that arrive in pieces.
|
|
The first call to
|
|
.I plumbunpackpartial
|
|
for a given message must be sufficient to unpack the header;
|
|
subsequent calls permit unpacking messages with long data sections.
|
|
For each call,
|
|
.I buf
|
|
points to the beginning of the complete message received so far, and
|
|
.I n
|
|
reports the total number of bytes received for that message.
|
|
If the message is complete, the return value will be as in
|
|
.IR plumbunpack .
|
|
If not, and
|
|
.I morep
|
|
is not null, the return value will be
|
|
.B nil
|
|
and
|
|
.BR * 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
|
|
.IB buf + n \f1,
|
|
and the message unpacked again.
|
|
If an error is encountered, the return value will be
|
|
.B nil
|
|
and
|
|
.BI * morep
|
|
will be zero.
|
|
.PP
|
|
.I Plumbpackattr
|
|
converts the list
|
|
.I a
|
|
of
|
|
.B 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.
|
|
.I Plumbunpackattr
|
|
converts the null-terminated string
|
|
.I a
|
|
back into a list of
|
|
.I Plumbattr
|
|
structures.
|
|
.PP
|
|
.I Plumblookup
|
|
searches the
|
|
.B Plumbattr
|
|
list
|
|
.I a
|
|
for an attribute with the given
|
|
.I 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.
|
|
.PP
|
|
.I Plumbaddattr
|
|
appends the
|
|
.I new
|
|
.B Plumbattr
|
|
(which may be a list) to the attribute list
|
|
.IR a
|
|
and returns the new list.
|
|
.I Plumbdelattr
|
|
searches the list
|
|
.I a
|
|
for the first attribute with name
|
|
.I name
|
|
and deletes it from the list, returning the resulting list.
|
|
.I Plumbdelattr
|
|
is a no-op if no such attribute exists.
|
|
.SH SOURCE
|
|
.B /sys/src/libplumb
|
|
.SH SEE ALSO
|
|
.IR plumb (1),
|
|
.IR event (2),
|
|
.IR plumber (4),
|
|
.IR plumb (6)
|
|
.SH DIAGNOSTICS
|
|
When appropriate, including when a
|
|
.I plumbsend
|
|
fails, these routine set
|
|
.IR errstr .
|