o5r/plan9port
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

new man pages

Browse source
This commit is contained in:
rsc 2005-02-11 19:21:47 +00:00
parent 7442c7ac4b
commit d93fca6a7a
21 changed files with 3089 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

10
man/man3/9p.3
View file

@ -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

30
man/man3/9pclient.3
View file

@ -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

3
man/man3/INDEX
View file

@ -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

422
man/man3/auth.3 Normal file
View file

@ -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 .

222
man/man3/authsrv.3 Normal file
View file

@ -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.

87
man/man3/encrypt.3 Normal file
View file

@ -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).

476
man/man3/ndb.3 Normal file
View file

@ -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.

18
man/man3/open.3
View file

@ -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.

48
man/man3/readcons.3 Normal file
View file

@ -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

29
man/man3/sysfatal.3
View file

@ -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"