Subversion Repositories planix.SVN

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