Lots of man pages.

1 files changed, 240 insertions, 0 deletions

diff --git a/man/man3/plumb.3 b/man/man3/plumb.3
new file mode 100644
index 00000000..e51a658f
--- /dev/null
+++ b/man/man3/plumb.3
@@ -0,0 +1,240 @@
+.TH PLUMB 3
+.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(Plumbattra *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 Plumbattr
+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 .