.TH NDB 2 .SH NAME ndbopen, ndbcat, ndbchanged, ndbclose, ndbreopen, ndbsearch, ndbsnext, ndbgetvalue, ndbfree, ipattr, mkptrname, ndbgetipaddr, ndbipinfo, csipinfo, ndbhash, ndbparse, csgetvalue, ndbfindattr, dnsquery, ndbdiscard, ndbconcatenate, ndbreorder, ndbsubstitute, ndbdedup \- network database .SH SYNOPSIS .B #include .br .B #include .br .B #include .br .B #include .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 void mkptrname(char *ip, char *rip, int rlen); .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 Ndbtuple* ndbdedup(Ndbtuple *t) .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 Mkptrname converts the address string .I ip to a reverse lookup domain-name, returned in .IR rip . The .I rlen argument gives the maximum size of the .I rip buffer including the NUL-terminator. If .I ip already is a reverse lookup domain-name or has invalid ip address syntax, then .I ip is copied into .I rip verbatim. .PP .I Ndbgetipaddr looks in .I db for entries matching .I sys as the value of a .B sys= or .B dom= attribute/value pair and returns all IP addresses. 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 csgetvalue is to .IR ndbgetvalue . .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 the attributes on each returned tuple line: .TP .B ip find the IP addresses. Returns domain name .RI ( dom ) and ip address .RI ( ip ). .TP .B ipv6 find the IPv6 addresses. Returns domain name .RI ( dom ) and ipv6 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 srv get the service records. Returns the priority of target host .RI ( pri ), relative weight .RI ( weight ) for entries with the same priority, port on this target host of this service .RI ( port ), and the domain name of the target host .RI ( target ). .TP .B txt get the descriptive text. The semantics of the text depends on the domain. .TP .B ns name servers. Returns domain name .RI ( dom ) and name server .RI ( ns ). .TP .B caa get the certificate authority records. Returns the .RI ( tag ) and .RI ( flags ). .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 attr/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 Ndbdedup removes duplicate attr/val pairs from tuple list .IR t . .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)