build: Better Build System

1 files changed, 366 insertions, 0 deletions

diff --git a/static/plan9-4e/man2/ndb.2 b/static/plan9-4e/man2/ndb.2
new file mode 100644
index 00000000..9386686e
--- /dev/null
+++ b/static/plan9-4e/man2/ndb.2
@@ -0,0 +1,366 @@
+.TH NDB 2
+.SH NAME
+ndbopen, ndbcat, ndbclose, ndbreopen, ndbsearch, ndbsnext, ndbgetval, ndbfree, ipattr, ndbipinfo, csipinfo, ndbhash, ndbparse, csgetval, ndblookval, dnsquery \- 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
+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
+Ndbtuple*	ndbgetval(Ndb *db, Ndbs *s, char *attr, char *val,
+.br
+.B
+		char *rattr, char *buf)
+.PP
+.B
+Ndbtuple*	csgetval(char *netroot, char *attr, char *val, char *rattr, char *buf)
+.PP
+.B
+void	ndbfree(Ndbtuple *db)
+.PP
+.B
+char*	ipattr(char *name)
+.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*	ndblookval(Ndbtuple *entry, Ndbtuple *line, char *attr, char *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[Ndbvlen];
+        Ndbtuple  *entry;
+        Ndbtuple  *line;
+        ulong     ptr;    /* for the application; starts 0 */
+};
+.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 Ndbgetval
+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 copies the value associated with
+.I rattr
+into
+.IR buf .
+.I Buf
+must point to an area at least
+.I Ndbvlen
+long.
+.I Csgetval
+is like
+.I ndbgetval
+but queries the connection server
+instead of looking directly at the database.
+It's 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 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 ipsubmask=255.255.255.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 last three calls 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 Ndblookval
+searches 
+.I entry
+for the tuple
+with attribute
+.IR attr ,
+copies the value into
+.IR to ,
+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.
+.SH FILES
+.BR /lib/ndb "    directory of network database files
+.SH SOURCE
+.B /sys/src/libndb
+.SH SEE ALSO
+.IR ndb (6)
+.IR ndb (8)
+.SH DIAGNOSTICS
+These routines set
+.IR errstr .