10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
477 lines
9.5 KiB
Groff
477 lines
9.5 KiB
Groff
.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
|
|
.MR ndb 7 .
|
|
.PP
|
|
.I Ndbopen
|
|
opens the database
|
|
.I file
|
|
and calls
|
|
.MR malloc 3
|
|
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
|
|
.MR malloc 3
|
|
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
|
|
.MR ndb 1
|
|
.MR 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.
|