plan9-gpl/sys/man/2/ndb

.TH NDB 2
.SH NAME
ndbopen, ndbcat, ndbchanged, ndbclose, ndbreopen, ndbsearch, ndbsnext, ndbgetvalue, ndbfree, ipattr, ndbgetipaddr, ndbipinfo, csipinfo, ndbhash, ndbparse, csgetvalue, ndbfindattr, dnsquery, ndbdiscard, ndbconcatenate, ndbreorder, ndbsubstitute, ndbgetval, csgetval, 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
int	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,
.B
		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,
.br
.B		char **attrs, 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)
.PP
.B
void	ndbsetmalloctag(Ndbtuple *t, uintptr tag)
.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
throws out any cached information
for the database files associated with
.I db
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 NUL-terminated value associated with
.IR rattr .
If
.I tp
is non nil,
.I *tp
will point to the entry.  Otherwise the entry will be freed.
.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 .
If any
.I attrs
begin with
.LR @ ,
the
.L @
is excluded from the attribute name,
but causes any corresponding value returned
to be a resolved IP address(es), not a name.
For example, consider the following database entries describing a network,
a subnetwork, and a system.
.IP
.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
.IP
.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 logically arranged into lines using the
.B line
field in 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 periodically
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.
.PP
.I Ndbsetmalloctag
sets the malloc tag
(see
.I setmalloctag
in
.IR malloc (2))
of each tuple in the list
.I t
to
.IR tag .
.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
.IR Ndbgetvalue ,
.IR csgetvalue ,
and
.I ndblookvalue
set
.I errstr
to
.L "buffer too short"
if the buffer provided isn't long enough for the
returned value.
.SH BUGS
.IR Ndbgetval ,
.IR csgetval ,
and
.I ndblookval
are deprecated versions of
.IR ndbgetvalue ,
.IR csgetvalue ,
and
.IR ndblookvalue .
They expect a fixed 64 byte long result
buffer and existed when the values of a
.I Ndbtuple
structure were fixed length.