new man pages

10 files changed, 1338 insertions, 7 deletions

diff --git a/man/man3/9p.3 b/man/man3/9p.3
index 109c452e..56f0cef3 100644
--- a/man/man3/9p.3
+++ b/man/man3/9p.3
@@ -46,6 +46,7 @@ typedef struct Srv {
 
 	void		(*destroyfid)(Fid *fid);
 	void		(*destroyreq)(Req *r);
+	void		(*start)(Srv *s);
 	void		(*end)(Srv *s);
 	void*	aux;
 
@@ -308,7 +309,7 @@ These constraints are checked while the server executes.
 If a service function fails to do something it ought to have,
 .I srv
 will call
-.I endsrv
+.I end
 and then abort.
 .TP 
 .I Auth
@@ -654,6 +655,7 @@ has been sent.
 .PP
 .IR Destroyfid ,
 .IR destroyreq ,
+.IR start ,
 and
 .I end
 are auxiliary functions, not called in direct response to 9P requests.
@@ -684,6 +686,12 @@ is called to allow the program to dispose of the
 .IB r -> aux
 pointer.
 .TP
+.I Start
+Before the 9P service loop begins, the service proc calls
+.I start
+so that the server can run any initialization that must be
+done from inside the service proc.
+.TP
 .I End
 Once the 9P service loop has finished
 (end of file been reached on the service pipe
diff --git a/man/man3/9pclient.3 b/man/man3/9pclient.3
index 4db33491..36b17e04 100644
--- a/man/man3/9pclient.3
+++ b/man/man3/9pclient.3
@@ -1,6 +1,6 @@
 .TH 9PCLIENT 3
 .SH NAME
-CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd, fspread, fspwrite, fsread, fsreadn, fswrite \- 9P client library
+CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd, fspread, fspwrite, fsread, fsreadn, fsseek, fswrite \- 9P client library
 .SH SYNOPSIS
 .B #include <u.h>
 .PP
@@ -27,6 +27,9 @@ void	fsunmount(CFsys *fsys)
 CFsys*	fsinit(int fd)
 .PP
 .B
+CFsys*	nsinit(char *name)
+.PP
+.B
 int	fsversion(CFsys *fsys, int msize, char *version, int nversion)
 .PP
 .B
@@ -85,6 +88,9 @@ int	fsdirfwstat(CFid *fid, Dir *d)
 .PP
 .B
 int	fsopenfd(CFsys *fs, char *path, int mode)
+.PP
+.B
+CFsys*	nsopen(char *name, char *aname, char *path, int mode)
 .SH DESCRIPTION
 The
 .I 9pclient
@@ -121,6 +127,7 @@ returns the
 corresponding to this root.
 .PP
 .IR Fsinit ,
+.IR nsinit ,
 .IR fsversion ,
 .IR fsauth ,
 .IR fsattach ,
@@ -135,7 +142,12 @@ and
 allocates a new 
 .B CFsys*
 corresponding to a 9P conversation on the file descriptor
-.IR fd .
+.I fd
+and then calls
+.IR fsversion
+to initialize the connection.
+.I Nsinit
+does the same for name space services.
 .I Fsversion
 executes a 
 .IR version (9p)
@@ -328,11 +340,23 @@ the only signal of a read or write error is the closing of the pipe.
 The file descriptor remains valid even after the
 .B CFsys
 is unmounted.
+.PP
+.I Nsopen
+opens a single file on a name space server: it runs
+.IR nsmount ,
+.IR fsopen ,
+and then
+.IR fsunmount .
 .SH SOURCE
 .B \*9/src/lib9pclient
 .SH SEE ALSO
 .IR intro (4),
-.IR intro (9p)
+.IR intro (9p),
+.I fsaopen
+and
+.I nsaopen
+in
+.IR auth (3)
 .SH BUGS
 The implementation
 should use a special version string to distinguish between
diff --git a/man/man3/INDEX b/man/man3/INDEX
index d0bb7418..a2e4abd2 100644
--- a/man/man3/INDEX
+++ b/man/man3/INDEX
@@ -982,6 +982,8 @@ runestrncmp runestrcat.3
 runestrncpy runestrcat.3
 runestrrchr runestrcat.3
 runestrstr runestrcat.3
+search searchpath.3
+searchpath searchpath.3
 hmac_md5 sechash.3
 hmac_sha1 sechash.3
 md4 sechash.3
@@ -1116,6 +1118,7 @@ threadsetgrp thread.3
 threadsetname thread.3
 threadsetstate thread.3
 threadspawn thread.3
+threadspawnl thread.3
 threadwaitchan thread.3
 yield thread.3
 nsec time.3
diff --git a/man/man3/auth.3 b/man/man3/auth.3
new file mode 100644
index 00000000..50620cc6
--- /dev/null
+++ b/man/man3/auth.3
@@ -0,0 +1,422 @@
+.TH AUTH 3
+.SH NAME
+auth_proxy, fauth_proxy, auth_allocrpc, auth_freerpc, auth_rpc, auth_getkey, amount_getkey, auth_freeAI, auth_chuid, auth_challenge, auth_response, auth_freechal, auth_respond, auth_userpasswd, auth_getuserpasswd, auth_getinfo\- routines for authenticating users
+.SH SYNOPSIS
+.nf
+.PP
+.ft L
+#include <u.h>
+#include <libc.h>
+#include <auth.h>
+.fi
+.ta 11n +4n +4n +4n +4n +4n +4n
+.\" .PP
+.\" .B
+.\" int		newns(char *user, char *nsfile);
+.\" .PP
+.\" .B
+.\" int		addns(char *user, char *nsfile);
+.\" .PP
+.\" .B
+.\" int		amount(int fd, char *old, int flag, char *aname);
+.\" .PP
+.\" .B
+.\" int		login(char *user, char *password, char *namespace);
+.\" .PP
+.\" .B
+.\" int		noworld(char *user);
+.PP
+.B
+AuthInfo*	auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...);
+.PP
+.B
+AuthInfo*	fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey,
+.br
+.B			char *params);
+.PP
+.B
+AuthRpc*	auth_allocrpc(void);
+.PP
+.B
+void		auth_freerpc(AuthRpc *rpc);
+.PP
+.B
+uint		auth_rpc(AuthRpc *rpc, char *verb, void *a, int n);
+.PP
+.B
+int		auth_getkey(char *proto, char *dom);
+.PP
+.B
+int		(*amount_getkey)(char*, char*);
+.PP
+.B
+void		auth_freeAI(AuthInfo *ai);
+.PP
+.B
+int			auth_chuid(AuthInfo *ai, char *ns);
+.PP
+.B
+Chalstate*	auth_challenge(char *fmt, ...);
+.PP
+.B
+AuthInfo*	auth_response(Chalstate*);
+.PP
+.B
+void		auth_freechal(Chalstate*);
+.PP
+.B
+int			auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...);
+.PP
+.B
+AuthInfo*	auth_userpasswd(char*user, char*password);
+.PP
+.B
+UserPasswd*	auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...);
+.PP
+.B
+AuthInfo*	auth_getinfo(AuthRpc *rpc);
+.PP
+.B
+#include <9pclient.h>
+.PP
+.B
+CFsys*	fsamount(int fd, char *aname);
+.PP
+.B
+CFsys*	nsamount(char *name, char *aname);
+.SH DESCRIPTION
+.PP
+This library, in concert with
+.IR factotum (4),
+is used to authenticate users.
+It provides the primary interface to
+.IR factotum .
+.\" .PP
+.\" .I Newns
+.\" builds a name space for
+.\" .IR user .
+.\" It opens the file
+.\" .I nsfile
+.\" .RB ( /lib/namespace
+.\" is used if
+.\" .I nsfile
+.\" is null),
+.\" copies the old environment, erases the current name space,
+.\" sets the environment variables
+.\" .B user
+.\" and
+.\" .BR home ,
+.\" and interprets the commands in
+.\" .IR nsfile .
+.\" The format of
+.\" .I nsfile
+.\" is described in
+.\" .IR namespace (6).
+.\" .PP
+.\" .I Addns
+.\" also interprets and executes the commands in
+.\" .IR nsfile .
+.\" Unlike
+.\" .I newns
+.\" it applies the command to the current name space
+.\" rather than starting from scratch.
+.\" .PP
+.\" .I Amount
+.\" is like
+.\" .I mount
+.\" but performs any authentication required.
+.\" It should be used instead of
+.\" .I mount
+.\" whenever the file server being mounted requires authentication.
+.\" See
+.\" .IR bind (2)
+.\" for a definition of the arguments to
+.\" .I mount
+.\" and
+.\" .IR amount .
+.\" .PP
+.\" .I Login
+.\" changes the user id of the process
+.\" .I user
+.\" and recreates the namespace using the file
+.\" .I namespace
+.\" (default
+.\" .BR /lib/nnamespace ).
+.\" It uses
+.\" .I auth_userpassword
+.\" and
+.\" .IR auth_chuid .
+.\" .PP
+.\" .I Noworld
+.\" returns 1 if the user is in the group
+.\" .B noworld
+.\" in
+.\" .BR /adm/users .
+.\" Otherwise, it returns 0.
+.\" .I Noworld
+.\" is used by telnetd and ftpd to provide sandboxed
+.\" access for some users.
+.PP
+The following routines use the
+.B AuthInfo
+structure returned after a successful authentication by
+.IR factotum (4).
+.PP
+.ne 8
+.EX
+.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
+typedef struct
+{
+	char	*cuid;		/* caller id */
+	char	*suid;		/* server id */
+	char	*cap;			/* capability */
+	int	nsecret;		/* length of secret */
+	uchar	*secret;		/* secret */
+} AuthInfo;
+.EE
+.sp
+The fields
+.B cuid
+and
+.B suid
+point to the authenticated ids of the client and server.
+.B Cap
+is a capability returned only to the server.
+It is meaningful only on Plan 9.
+.\" It can be passed to the
+.\" .IR cap (3)
+.\" device to change the user id of the process.
+.B Secret
+is an
+.BR nsecret -byte
+shared secret that can be used by the client and server to
+create encryption and hashing keys for the rest of the
+conversation.
+.PP
+.I Auth_proxy
+proxies an authentication conversation between a remote
+server reading and writing
+.I fd
+and a
+.I factotum
+file, as opened by
+.IR auth_allocrpc.
+An
+.B sprint
+(see
+.IR print (2))
+of 
+.I fmt
+and the variable arg list yields a key template (see
+.IR factotum (4))
+specifying the key to use.
+The template must specify at least the protocol (
+.BI proto= xxx )
+and the role (either
+.B role=client
+or
+.BR role=server ).
+.I Auth_proxy
+either returns an allocated
+.B AuthInfo
+structure, or sets the error string and
+returns nil.
+.PP
+.I Fauth_proxy
+can be used instead of
+.I auth_proxy
+if a single connection to
+.I factotum
+will be used for multiple authentications.
+This is necessary, for example, for
+.I newns
+which must open the
+.I factotum
+file before wiping out the namespace.
+.I Fauth_proxy
+takes as an argument a pointer to an
+.B AuthRpc
+structure which contains an fd for an open connection to
+.I factotum
+in addition to storage and state information for
+the protocol.
+An
+.B AuthRpc
+structure is obtained by calling
+.IR auth_allocrpc .
+.I Auth_allocrpc
+arranges a connection to
+.IR factotum ,
+either by opening
+.B /mnt/factotum/rpc
+or by using 
+.IR 9pclient (3)
+to connect to a
+.B factotum
+service posted in the current name space.
+The returned connection 
+is freed using
+.IR auth_freerpc .
+Individual commands can be sent to
+.IR factotum (4)
+by invoking
+.IR auth_rpc .
+.PP
+Both
+.I auth_proxy
+and
+.I fauth_proxy
+take a pointer to a routine,
+.IR getkey ,
+to invoke should
+.I factotum
+not posess a key for the authentication.  If
+.I getkey
+is nil, the authentication fails.
+.I Getkey
+is called with a key template for the desired
+key.
+We have provided a generic routine,
+.IR auth_getkey ,
+which queries the user for
+the key information and passes it to
+.IR factotum .
+This is the default for the global variable,
+.IR amount_getkey ,
+which holds a pointer to the key prompting routine used by
+.IR amount .
+.PP
+.I Auth_chuid
+uses the
+.B cuid
+and
+.B cap
+fields of an
+.B AuthInfo
+structure to change the user id of the current
+process and uses
+.IR ns ,
+default
+.BR /lib/namespace ,
+to build it a new name space.
+.PP
+.I Auth_challenge
+and
+.I auth_response
+perform challenge/response protocols with
+.IR factotum .
+State between the challenge and response phase are
+kept in the
+.B Chalstate
+structure:
+.sp
+.EX
+struct Chalstate
+{
+	char	*user;
+	char	chal[MAXCHLEN];
+	int	nchal;
+	void	*resp;
+	int	nresp;
+
+/* for implementation only */
+	int	afd;
+	AuthRpc	*rpc;
+	char	userbuf[MAXNAMELEN];
+	int	userinchal;
+};
+.EE
+.sp
+.I Auth_challenge
+requires a key template generated by an
+.B sprint
+of
+.I fmt
+and the variable arguments.  It must contain the protocol
+(\fBproto=\fIxxx\fR)
+and depending on the protocol, the user name (
+.BI user= xxx \fR).\fP
+.B P9cr
+and
+.B vnc
+expect the user specified as an attribute in
+the key template and
+.BR apop ,
+.BR cram ,
+and
+.BR chap
+expect it in the 
+.B user
+field of the arg to
+.IR auth_response .
+For all protocols, the response is returned
+to
+.I auth_response
+in the
+.I resp
+field of the
+.BR Chalstate .
+.I Chalstate.nresp
+must be the length of the response.
+.PP
+Supply to
+.I auth_respond
+a challenge string and the fmt and args specifying a key,
+and it will use
+.I factotum
+to return the proper user and response.
+.PP
+.I Auth_userpasswd
+verifies a simple user/password pair.
+.I Auth_getuserpasswd
+retrieves a user/password pair from
+.I factotum
+if permitted.
+.PP
+.I Auth_getinfo
+reads an
+.B AuthInfo
+message from factotum
+and converts it into a structure.  It is only
+used by the other routines in this library when
+communicating with
+.IR factotum .
+.PP
+.ne 8
+.EX
+.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
+typedef struct UserPasswd {
+	char	*user;
+	char	*passwd;
+} UserPasswd;
+.EE
+.sp
+.PP
+.I Auth_freeAI
+is used to free an
+.B AuthInfo
+structure returned by one of these routines.
+Similary
+.I auth_freechal
+frees a challenge/response state.
+.PP
+.I Fsamount
+and
+.I nsamount
+are like
+.I fsmount
+and
+.I nsmount
+(see
+.IR 9pclient (3))
+but use
+.I factotum
+to authenticate to the file servers.
+.SH SOURCE
+.B \*9/src/libauth
+.SH SEE ALSO
+.IR factotum (4),
+.IR authsrv (3)
+.SH DIAGNOSTICS
+These routines set
+.IR errstr .
diff --git a/man/man3/authsrv.3 b/man/man3/authsrv.3
new file mode 100644
index 00000000..a8d6b5e7
--- /dev/null
+++ b/man/man3/authsrv.3
@@ -0,0 +1,222 @@
+.TH AUTHSRV 3
+.SH NAME
+authdial, passtokey, nvcsum, readnvram, convT2M, convM2T, convTR2M, convM2TR, convA2M, convM2A, convPR2M, convM2PR, _asgetticket, _asrdresp \- routines for communicating with authentication servers
+.SH SYNOPSIS
+.nf
+.PP
+.ft L
+#include <u.h>
+#include <libc.h>
+#include <authsrv.h>
+.fi
+.ta 8n +4n +4n +4n +4n +4n +4n
+.PP
+.B
+int	authdial(char *netroot, char *ad);
+.PP
+.B
+int	passtokey(char key[DESKEYLEN], char *password)
+.PP
+.B
+uchar	nvcsum(void *mem, int len)
+.PP
+.B
+int	readnvram(Nvrsafe *nv, int flag);
+.PPP
+.B
+int	convT2M(Ticket *t, char *msg, char *key)
+.PP
+.B
+void	convM2T(char *msg, Ticket *t, char *key)
+.PP
+.B
+int	convA2M(Authenticator *a, char *msg, char *key)
+.PP
+.B
+void	convM2A(char *msg, Authenticator *a, char *key)
+.PP
+.B
+int	convTR2M(Ticketreq *tr, char *msg)
+.PP
+.B
+void	convM2TR(char *msg, Ticketreq *tr)
+.PP
+.B
+int	convPR2M(Passwordreq *pr, char *msg, char *key)
+.PP
+.B
+void	convM2PR(char *msg, Passwordreq *pr, char *key)
+.PP
+.B
+int	_asgetticket(int fd, char *trbuf, char *tbuf);
+.PP
+.B
+int	_asrdresp(int fd, char *buf, int len);
+.SH DESCRIPTION
+.PP
+.I Authdial
+dials an authentication server over the
+network rooted at
+.IR net ,
+default
+.BR /net  .
+The authentication domain,
+.IR ad ,
+specifies which server to call.
+If
+.I ad
+is non-nil,
+the network database
+(see
+.IR ndb (1))
+is queried for an entry which contains
+.B authdom=\fIad\fP
+or
+.BR dom=\fIad\fP ,
+the former having precedence,
+and which also contains an
+.B auth
+attribute.
+The string dialed is then
+.I netroot\fP!\fIserver\fP!ticket
+where
+.I server
+is the value of the
+.B auth
+attribute.
+If no entry is found, the error string is
+set to ``no authentication server found''
+and -1 is returned.
+If
+.I authdom
+is nil, the string
+.IB netroot !$auth! ticket
+is used to make the call.
+.PP
+.I Passtokey
+converts
+.I password
+into a DES key and stores the result in
+.IR key .
+It returns 0 if
+.I password
+could not be converted,
+and 1 otherwise.
+.PP
+.I Readnvram
+reads authentication information into the structure:
+.EX
+.ta 4n +4n +8n +4n +4n +4n +4n
+	struct Nvrsafe
+	{
+		char	machkey[DESKEYLEN];
+		uchar	machsum;
+		char	authkey[DESKEYLEN];
+		uchar	authsum;
+		char	config[CONFIGLEN];
+		uchar	configsum;
+		char	authid[ANAMELEN];
+		uchar	authidsum;
+		char	authdom[DOMLEN];
+		uchar	authdomsum;
+	};
+.EE
+.PP
+On Sparc, MIPS, and SGI machines this information is
+in non-volatile ram, accessible in the file
+.BR #r/nvram .
+On x86s and Alphas
+.I readnvram
+successively opens the following areas stopping with the
+first to succeed:
+.PP
+\- the partition named by the
+.B $nvram
+environment variable
+(commonly set via
+.IR plan9.ini (8))
+.br
+\- the partition
+.B #S/sdC0/nvram
+.br
+\- a file called
+.B plan9.nvr
+in the partition
+.B #S/sdC0/9fat
+.br
+\- the partition
+.B #S/sd00/nvram
+.br
+\- a file called
+.B plan9.nvr
+in the partition
+.B #S/sd00/9fat
+.br
+\- a file called
+.B plan9.nvr
+on a DOS floppy in drive 0
+.br
+\- a file called
+.B plan9.nvr
+on a DOS floppy in drive 1
+.PP
+The
+.IR nvcsum s
+of the fields
+.BR machkey ,
+.BR authid ,
+and
+.B authdom
+must match their respective checksum or that field is zeroed.
+If
+.I flag
+is
+.B NVwrite
+or at least one checksum fails and
+.I flag
+is
+.BR NVwriteonerr ,
+.I readnvram
+will prompt for new values on
+.B #c/cons
+and then write them back to the storage area.
+.PP
+.IR ConvT2M ,
+.IR convA2M ,
+.IR convTR2M ,
+and
+.I convPR2M
+convert tickets, authenticators, ticket requests, and password change request
+structures into transmittable messages.
+.IR ConvM2T ,
+.IR convM2A ,
+.IR convM2TR ,
+and
+.I convM2PR
+are used to convert them back.
+.I Key
+is used for encrypting the message before transmission and decrypting
+after reception.
+.PP
+The routine
+.I _asgetresp
+receives either a character array or an error string.
+On error, it sets errstr and returns -1.  If successful,
+it returns the number of bytes received.
+.PP
+The routine
+.I _asgetticket
+sends a ticket request message and then uses
+.I _asgetresp
+to recieve an answer.
+.SH SOURCE
+.B \*9/src/libauthsrv
+.SH SEE ALSO
+.IR netkey (1),
+.IR dial (3),
+Plan 9's
+\fIauthsrv\fR(6).
+.SH DIAGNOSTICS
+These routines set
+.IR errstr .
+Integer-valued functions return -1 on error.
diff --git a/man/man3/encrypt.3 b/man/man3/encrypt.3
new file mode 100644
index 00000000..213f81da
--- /dev/null
+++ b/man/man3/encrypt.3
@@ -0,0 +1,87 @@
+.TH ENCRYPT 2
+.SH NAME
+encrypt, decrypt, netcrypt \- DES encryption
+.SH SYNOPSIS
+.B #include <u.h>
+.br
+.B #include <libc.h>
+.PP
+.B
+int	encrypt(void *key, void *data, int len)
+.PP
+.B
+int	decrypt(void *key, void *data, int len)
+.PP
+.B
+int	netcrypt(void *key, void *data)
+.SH DESCRIPTION
+.I Encrypt
+and
+.I decrypt
+perform DES encryption and decryption.
+.I Key
+is an array of
+.B DESKEYLEN
+(defined as 7 in
+.BR <auth.h> )
+bytes containing the encryption key.
+.I Data
+is an array of
+.I len
+bytes;
+it must be at least 8 bytes long.
+The bytes are encrypted or decrypted in place.
+.PP
+The DES algorithm encrypts an individual 8-byte block of data.
+.I Encrypt
+uses the following method to encrypt data longer than 8 bytes.
+The first 8 bytes are encrypted as usual.
+The last byte of the encrypted result
+is prefixed to the next 7 unencrypted bytes to make the next 8
+bytes to encrypt.
+This is repeated until fewer than 7 bytes remain unencrypted.
+Any remaining unencrypted bytes are encrypted with enough of the preceding
+encrypted bytes to make a full 8-byte block.
+.I Decrypt
+uses the inverse algorithm.
+.PP
+.I Netcrypt
+performs the same encryption as a SecureNet Key.
+.I Data
+points to an
+.SM ASCII
+string of decimal digits with numeric value between 0 and 10000.
+These digits are copied into an 8-byte buffer with trailing binary zero fill
+and encrypted as one DES block.
+The first four bytes are each formatted as two digit
+.SM ASCII
+hexadecimal numbers,
+and the string is copied into
+.IR data .
+.SH SOURCE
+.B /sys/src/libc/port
+.SH DIAGNOSTICS
+These routines return 1 if the data was encrypted,
+and 0 if the encryption fails.
+.I Encrypt
+and
+.I decrypt
+fail if the data passed is less than 8 bytes long.
+.I Netcrypt
+can fail if it is passed invalid data.
+.\" .SH SEE ALSO
+.\" .IR securenet (8)
+.SH BUGS
+The implementation is broken in a way that makes
+it unsuitable for anything but authentication.
+.PP
+To avoid name conflicts with the underlying system,
+.IR encrypt 
+and
+.IR decrypt
+are preprocessor macros defined as
+.IR p9encrypt
+and
+.IR p9decrypt ;
+see
+.IR intro (3).
diff --git a/man/man3/ndb.3 b/man/man3/ndb.3
new file mode 100644
index 00000000..fd5c54e1
--- /dev/null
+++ b/man/man3/ndb.3
@@ -0,0 +1,476 @@
+.TH NDB 3
+.SH NAME
+ndbopen, ndbcat, ndbchanged, ndbclose, ndbreopen, ndbsearch, ndbsnext, ndbgetvalue, ndbfree, ipattr, ndbgetipaddr, ndbipinfo, ndbhash, ndbparse, ndbfindattr, ndbdiscard, ndbconcatenate, ndbreorder, ndbsubstitute, ndbgetval, ndblookval \- network database
+.SH SYNOPSIS
+.B #include <u.h>
+.br
+.B #include <libc.h>
+.br
+.B #include <bio.h>
+.br
+.B #include <ndb.h>
+.ta \w'\fLNdbtuplexx 'u
+.PP
+.B
+Ndb*	ndbopen(char *file)
+.PP
+.B
+Ndb*	ndbcat(Ndb *db1, Ndb *db2)
+.PP
+.B
+Ndb*	ndbchanged(Ndb *db)
+.PP
+.B
+int	ndbreopen(Ndb *db)
+.PP
+.B
+void	ndbclose(Ndb *db)
+.PP
+.B
+Ndbtuple*	ndbsearch(Ndb *db, Ndbs *s, char *attr, char *val)
+.PP
+.B
+Ndbtuple*	ndbsnext(Ndbs *s, char *attr, char *val)
+.PP
+.B
+char*	ndbgetvalue(Ndb *db, Ndbs *s, char *attr, char *val,
+.br
+.B
+		char *rattr, Ndbtuple **tp)
+.\" .PP
+.\" .B
+.\" char*	csgetvalue(char *netroot, char *attr, char *val, char *rattr,
+.\" 		Ndbtuple **tp)
+.PP
+.B
+char*	ipattr(char *name)
+.PP
+.B
+Ndbtuple*	ndbgetipaddr(Ndb *db, char *sys);
+.PP
+.B
+Ndbtuple*	ndbipinfo(Ndb *db, char *attr, char *val, char **attrs,
+.br
+.B		int nattr)
+.\" .PP
+.\" .B
+.\" Ndbtuple*	csipinfo(char *netroot, char *attr, char *val, char **attrs,
+.\" .br
+.\" .B		int nattr)
+.PP
+.B
+ulong	ndbhash(char *val, int hlen)
+.PP
+.B
+Ndbtuple*	ndbparse(Ndb *db)
+.\" .PP
+.\" .B
+.\" Ndbtuple*	dnsquery(char *netroot, char *domainname, char *type)
+.PP
+.B
+Ndbtuple*	ndbfindattr(Ndbtuple *entry, Ndbtuple *line, char *attr)
+.PP
+.B
+void	ndbfree(Ndbtuple *db)
+.PP
+.B
+Ndbtuple*	ndbdiscard(Ndbtuple  *t, Ndbtuple *a)
+.PP
+.B
+Ndbtuple*	ndbconcatenate(Ndbtuple *a, Ndbtuple *b);
+.PP
+.B
+Ndbtuple*	ndbreorder(Ndbtuple *t, Ndbtuple *a);
+.PP
+.B
+Ndbtuple*	ndbsubstitute(Ndbtuple *t, Ndbtuple *from, Ndbtuple *to);
+.SH DESCRIPTION
+These routines are used by network administrative programs to search
+the network database.
+They operate on the database files described in
+.IR ndb (6).
+.PP
+.I Ndbopen
+opens the database
+.I file
+and calls
+.IR malloc (2)
+to allocate a buffer for it.
+If
+.I file
+is zero, all network database files are opened.
+.PP
+.I Ndbcat
+concatenates two open databases.  Either argument may be
+nil.
+.PP
+.I Ndbreopen
+checks if the database files associated with
+.I db
+have changed and if so throws out any cached information and reopens
+the files.
+.PP
+.I Ndbclose
+closes any database files associated with
+.I db
+and frees all storage associated with them.
+.PP
+.I Ndbsearch
+and
+.I ndbsnext
+search a database for an entry containing the
+attribute/value pair,
+.IR attr = val .
+.I Ndbsearch
+is used to find the first match and
+.I ndbsnext
+is used to find each successive match.
+On a successful search both return a linked list of
+.I Ndbtuple
+structures acquired by
+.IR malloc (2)
+that represent the attribute/value pairs in the
+entry.
+On failure they return zero.
+.IP
+.EX
+typedef struct Ndbtuple Ndbtuple;
+struct Ndbtuple {
+        char      attr[Ndbalen];
+        char      *val;
+        Ndbtuple  *entry;
+        Ndbtuple  *line;
+        ulong     ptr;    /* for the application; starts 0 */
+        char      valbuf[Ndbvlen];  /* initial allocation for val */
+};
+.EE
+.LP
+The
+.I entry
+pointers chain together all pairs in the entry in a null-terminated list.
+The
+.I line
+pointers chain together all pairs on the same line
+in a circular list.
+Thus, a program can implement 2 levels of binding for
+pairs in an entry.
+In general, pairs on the same line are bound tighter
+than pairs on different lines.
+.PP
+The argument
+.I s
+of
+.I ndbsearch
+has type
+.I Ndbs
+and should be pointed to valid storage before calling
+.IR ndbsearch ,
+which will fill it with information used by
+.I ndbsnext
+to link successive searches.
+The structure
+.I Ndbs
+looks like:
+.IP
+.EX
+typedef struct Ndbs Ndbs;
+struct Ndbs {
+        Ndb      *db;   /* data base file being searched */
+        ...
+        Ndbtuple *t;    /* last attribute value pair found */
+};
+.EE
+.LP
+The
+.I t
+field points to the pair within the entry matched by the
+.I ndbsearch
+or
+.IR ndbsnext .
+.PP
+.I Ndbgetvalue
+searches the database for an entry containing not only an
+attribute/value pair,
+.IR attr = val ,
+but also a pair with the attribute
+.IR rattr .
+If successful, it returns a malloced copy of the null terminated value associated with
+.IR  rattr .
+If
+.I tp
+is non nil,
+.I *tp
+will point to the entry.  Otherwise the entry will be freeed.
+.\" .PP
+.\" .I Csgetvalue
+.\" is like
+.\" .I ndbgetvalue
+.\" but queries the connection server
+.\" instead of looking directly at the database.
+.\" Its first argument specifies the network root to use.
+.\" If the argument is 0, it defaults to
+.\" \f5"/net"\f1.
+.PP
+.I Ndbfree
+frees a list of tuples returned by one of the other
+routines.
+.PP
+.I Ipattr
+takes the name of an IP system and returns the attribute
+it corresponds to:
+.RS
+.TP
+.B dom
+domain name
+.TP
+.B ip
+Internet number
+.TP
+.B sys
+system name
+.RE
+.PP
+.I Ndbgetipaddr
+looks in
+.I db
+for an entry matching
+.I sys
+as the value of a
+.B sys=
+or
+.B dom=
+attribute/value pair and returns all IP addresses in the entry.
+If
+.I sys
+is already an IP address, a tuple containing just
+that address is returned.
+.PP
+.I Ndbipinfo
+looks up Internet protocol information about a system.
+This is an IP aware search.  It looks first for information
+in the system's database entry and then in the database entries
+for any IP subnets or networks containing the system.
+The system is identified by the
+attribute/value pair,
+.IR attr = val .
+.I Ndbipinfo
+returns a list of tuples whose attributes match the
+attributes in the 
+.I n
+element array
+.IR attrs .
+For example, consider the following database entries describing a network,
+a subnetwork, and a system.
+.PP
+.EX
+ipnet=big ip=10.0.0.0
+	dns=dns.big.com
+	smtp=smtp.big.com
+ipnet=dept ip=10.1.1.0 ipmask=255.255.255.0
+	smtp=smtp1.big.com
+ip=10.1.1.4 dom=x.big.com
+	bootf=/386/9pc
+.EE
+.PP
+Calling
+.PP
+.EX
+   ndbipinfo(db, "dom", "x.big.com", ["bootf" "smtp" "dns"], 3)
+.EE
+.PP
+will return the tuples
+.BR bootf=/386/9pc ,
+.BR smtp=smtp1.big.com ,
+and
+.BR dns=dns.big.com .
+.\" .PP
+.\" .I Csipinfo
+.\" is to
+.\" .I ndbipinfo
+.\" as
+.\" .I csgetval
+.\" is to
+.\" .IR ndbgetval .
+.PP
+The next three routines are used by programs that create the
+hash tables and database files.
+.I Ndbhash
+computes a hash offset into a table of length
+.I hlen
+for the string
+.IR val .
+.I Ndbparse
+reads and parses the next entry from the database file.
+Multiple calls to
+.IR ndbparse
+parse sequential entries in the database file.
+A zero is returned at end of file.
+.\" .PP
+.\" .I Dnsquery
+.\" submits a query about
+.\" .I domainname
+.\" to the
+.\" .I ndb/dns
+.\" mounted at
+.\" .IB netroot /dns.
+.\" It returns a linked list of
+.\" .I Ndbtuple's
+.\" representing a single database entry.
+.\" The tuples are logicly arranged into lines using the
+.\" .B line
+.\" fieldin the structure.
+.\" The possible
+.\" .IR type 's
+.\" of query are and the attributes on each returned tuple line is:
+.\" .TP
+.\" .B ip
+.\" find the IP addresses.  Returns
+.\" domain name
+.\" .RI ( dom )
+.\" and ip address
+.\" .RI ( ip )
+.\" .TP
+.\" .B mx
+.\" look up the mail exchangers.  Returns preference
+.\" .RI ( pref )
+.\" and exchanger
+.\" .RI ( mx )
+.\" .TP
+.\" .B ptr
+.\" do a reverse query.  Here
+.\" .I domainname
+.\" must be an
+.\" .SM ASCII
+.\" IP address.  Returns reverse name
+.\" .RI ( ptr )
+.\" and domain name 
+.\" .RI ( dom )
+.\" .TP
+.\" .B cname
+.\" get the system that this name is a nickname for.  Returns the nickname
+.\" .RI ( dom )
+.\" and the real name
+.\" .RI ( cname )
+.\" .TP
+.\" .B soa
+.\" return the start of area record for this field.  Returns
+.\" area name
+.\" .RI ( dom ),
+.\" primary name server
+.\" .RI ( ns ),
+.\" serial number
+.\" .RI ( serial ),
+.\" refresh time in seconds
+.\" .RI ( refresh ),
+.\" retry time in seconds
+.\" .RI ( retry ),
+.\" expiration time in seconds
+.\" .RI ( expire ),
+.\" and minimum time to lie
+.\" .RI ( ttl ).
+.\" .TP
+.\" .B ns
+.\" name servers.  Returns domain name
+.\" .RI ( dom )
+.\" and name server
+.\" .RI ( ns )
+.PP
+.I Ndbfindattr
+searches 
+.I entry
+for the tuple
+with attribute
+.I attr
+and returns a pointer to the tuple.
+If
+.I line
+points to a particular line in the entry, the
+search starts there and then wraps around to the beginning
+of the entry.
+.PP
+All of the routines provided to search the database
+provide an always consistent view of the relevant
+files.  However, it may be advantageous for an application
+to read in the whole database using
+.I ndbopen
+and
+.I ndbparse
+and provide its own search routines.  The
+.I ndbchanged
+routine can be used by the application to periodicly
+check for changes.  It returns zero
+if none of the files comprising the database have
+changes and non-zero if they have.
+.PP
+Finally, a number of routines are provided for manipulating
+tuples.
+.PP
+.I Ndbdiscard
+removes attr/val pair
+.I a
+from tuple
+.I t
+and frees it.
+If
+.I a
+isn't in
+.I t
+it is just freed.
+.PP
+.I Ndbconcatenate
+concatenates two tuples and returns the result.  Either
+or both tuples may be nil.
+.PP
+.I Ndbreorder
+reorders a tuple
+.IR t
+to make the line containing attr/val pair
+.I a
+first in the entry and making
+.I a
+first in its line.
+.PP
+.I Ndbsubstitute
+replaces a single att/val pair
+.I from
+in
+.I t
+with the tuple
+.IR to .
+All attr/val pairs in
+.I to
+end up on the same line.
+.I from
+is freed.
+.SH FILES
+.TP
+.B \*9/ndb
+directory of network database files
+.PD
+.SH SOURCE
+.B \*9/src/libndb
+.SH SEE ALSO
+.IR ndb (1)
+.IR ndb (7)
+.SH DIAGNOSTICS
+.IR Ndbgetvalue
+and
+.I ndblookvalue
+set
+.I errstr
+to
+.B "buffer too short"
+if the buffer provided isn't long enough for the
+returned value.
+.SH BUGS
+.IR Ndbgetval
+and
+.I ndblookval
+are deprecated versions of
+.IR ndbgetvalue
+and
+.IR ndblookvalue .
+They expect a fixed 64 byte long result
+buffer and existed when the values of a
+.I Ndbtuple
+structure where fixed length.
diff --git a/man/man3/open.3 b/man/man3/open.3
index 51ff2cdf..ee0b276e 100644
--- a/man/man3/open.3
+++ b/man/man3/open.3
@@ -38,9 +38,12 @@ says to close the file when an
 or
 .I execl
 system call is made;
-and
 .B ORCLOSE
-says to remove the file when it is closed (by everyone who has a copy of the file descriptor).
+says to remove the file when it is closed (by everyone who has a copy of the file descriptor);
+and
+.B OAPPEND
+says to open the file in append-only mode, so that writes
+are always appended to the end of the file.
 .I Open
 fails if the file does not exist or the user does not have
 permission to open it for the requested purpose
@@ -145,3 +148,14 @@ allows the file descriptor to be reused.
 .SH DIAGNOSTICS
 These functions set
 .IR errstr .
+.SH BUGS
+Not all functionality is supported on all systems.
+.PP
+The
+.B DMAPPEND
+bit is not supported on any systems.
+.PP
+The implementation of
+.B ORCLOSE
+is to unlink the file after opening it, causing problems
+in programs that try to access the file by name before it is closed.
diff --git a/man/man3/readcons.3 b/man/man3/readcons.3
new file mode 100644
index 00000000..1f5d9865
--- /dev/null
+++ b/man/man3/readcons.3
@@ -0,0 +1,48 @@
+.TH READCONS 3
+.SH NAME
+readcons \- prompt console for input
+.SH SYNOPSIS
+.B
+#include <u.h>
+.PP
+.B
+#include <libc.h>
+.PP
+.B
+char *readcons(char *prompt, char *def, int secret)
+.SH DESCRIPTION
+.I Readcons
+prompts at the console for input.
+It returns a NUL-terminated buffer containing the input
+without a final newline.
+The buffer should be freed (and perhaps cleared first) 
+when no longer needed.
+.PP
+If the user types an empty string (just a newline) and
+.I def
+is non-zero, then a copy of 
+.I def
+is returned instead of the empty string.
+.PP
+If
+.I secret
+is non-zero, the input is not echoed to the screen.
+.SH EXAMPLE
+A stripped-down version of
+.IR netkey (1):
+.IP
+.EX
+pass = readcons("password", nil, 1);
+passtokey(key, pass);
+memset(pass, 0, strlen(pass));
+free(pass);
+for(;;){
+	chal = readcons("challenge", nil, 0);
+	sprint(buf, "%d", strtol(chal, 0, 10));
+	free(chal);
+	netcrypt(key, buf);
+	print("response: %s\n", buf);
+}
+.EE
+.SH SOURCE
+.B \*9/src/lib9/readcons.c
diff --git a/man/man3/sysfatal.3 b/man/man3/sysfatal.3
index 615e39f1..180a3406 100644
--- a/man/man3/sysfatal.3
+++ b/man/man3/sysfatal.3
@@ -1,12 +1,15 @@
 .TH SYSFATAL 3
 .SH NAME
-sysfatal \- system error messages
+syslog, sysfatal \- system error messages
 .SH SYNOPSIS
 .B #include <u.h>
 .br
 .B #include <libc.h>
 .PP
 .B
+void syslog(int cons, char *logname, char *fmt, ...)
+.PP
+.B
 void sysfatal(char *fmt, ...)
 .SH DESCRIPTION
 .I Sysfatal
@@ -28,6 +31,30 @@ interface to process its arguments.
 If
 .B argv0
 is null, it is ignored and the following colon and space are suppressed.
+.PP
+.I Syslog
+logs messages in the file named by
+.I logname
+in the directory
+.B \*9/log ;
+the file must already exist and is opened append-only.
+.I Logname
+must contain no slashes.
+The message is a line with several fields:
+the name of the machine writing the message;
+the date and time;
+the message specified by the 
+.IR print (2)
+format
+.I fmt
+and any following arguments;
+and a final newline.
+If
+.I cons
+is set or the log file cannot be opened, the message is also printed
+on the system console.
+.I Syslog
+can be used safely in multi-threaded programs.
 .SH SOURCE
 .B \*9/src/lib9/sysfatal.c
 .SH "SEE ALSO"