glenda.party
term% ls -F
term% cat index.txt
NDB(2)                        System Calls Manual                       NDB(2)



NAME
       ndbopen,  ndbcat, ndbchanged, ndbclose, ndbreopen, ndbsearch, ndbsnext,
       ndbgetvalue, ndbfree, ipattr, ndbgetipaddr, ndbipinfo,  csipinfo,  ndb‐
       hash,  ndbparse, csgetvalue, ndbfindattr, dnsquery, ndbdiscard, ndbcon‐
       catenate, ndbreorder, ndbsubstitute, ndbgetval, csgetval, ndblookval  -
       network database

SYNOPSIS
       #include <u.h>
       #include <libc.h>
       #include <bio.h>
       #include <ndb.h>

       Ndb*       ndbopen(char *file)

       Ndb*       ndbcat(Ndb *db1, Ndb *db2)

       int        ndbchanged(Ndb *db)

       int        ndbreopen(Ndb *db)

       void       ndbclose(Ndb *db)

       Ndbtuple*  ndbsearch(Ndb *db, Ndbs *s, char *attr, char *val)

       Ndbtuple*  ndbsnext(Ndbs *s, char *attr, char *val)

       char*      ndbgetvalue(Ndb *db, Ndbs *s, char *attr, char *val,
                  char *rattr, Ndbtuple **tp)

       char*      csgetvalue(char    *netroot,    char   *attr,   char   *val,
                  char *rattr, Ndbtuple **tp)

       char*      ipattr(char *name)

       Ndbtuple*  ndbgetipaddr(Ndb *db, char *sys);

       Ndbtuple*  ndbipinfo(Ndb *db, char *attr, char *val, char **attrs,
                  int nattr)

       Ndbtuple*  csipinfo(char *netroot, char *attr, char *val,
                  char **attrs, int nattr)

       ulong      ndbhash(char *val, int hlen)

       Ndbtuple*  ndbparse(Ndb *db)

       Ndbtuple*  dnsquery(char *netroot, char *domainname, char *type)

       Ndbtuple*  ndbfindattr(Ndbtuple *entry, Ndbtuple *line, char *attr)

       void       ndbfree(Ndbtuple *db)

       Ndbtuple*  ndbdiscard(Ndbtuple  *t, Ndbtuple *a)

       Ndbtuple*  ndbconcatenate(Ndbtuple *a, Ndbtuple *b)

       Ndbtuple*  ndbreorder(Ndbtuple *t, Ndbtuple *a)

       Ndbtuple*  ndbsubstitute(Ndbtuple *t, Ndbtuple *from, Ndbtuple *to)

       void       ndbsetmalloctag(Ndbtuple *t, uintptr tag)

DESCRIPTION
       These routines are used by network administrative  programs  to  search
       the  network database.  They operate on the database files described in
       ndb(6).

       Ndbopen opens the database file and calls malloc(2) to allocate a  buf‐
       fer for it.  If file is zero, all network database files are opened.

       Ndbcat concatenates two open databases.  Either argument may be nil.

       Ndbreopen  throws  out  any  cached  information for the database files
       associated with db and reopens the files.

       Ndbclose closes any database files associated with  db  and  frees  all
       storage associated with them.

       Ndbsearch  and  ndbsnext  search a database for an entry containing the
       attribute/value pair, attr=val.  Ndbsearch is used to  find  the  first
       match  and  ndbsnext  is used to find each successive match.  On a suc‐
       cessful search  both  return  a  linked  list  of  Ndbtuple  structures
       acquired  by  malloc(2) that represent the attribute/value pairs in the
       entry.  On failure they return zero.

              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 */
              };

       The entry pointers chain together all pairs in the entry in a null-ter‐
       minated  list.   The 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.

       The argument s of ndbsearch has type Ndbs  and  should  be  pointed  to
       valid  storage before calling ndbsearch, which will fill it with infor‐
       mation used by ndbsnext to link  successive  searches.   The  structure
       Ndbs looks like:

              typedef struct Ndbs Ndbs;
              struct Ndbs {
                      Ndb      *db;   /* data base file being searched */
                      ...
                      Ndbtuple *t;    /* last attribute value pair found */
              };

       The  t  field  points  to the pair within the entry matched by the ndb‐
       search or ndbsnext.

       Ndbgetvalue searches the database for an entry containing not  only  an
       attribute/value  pair,  attr=val,  but  also  a pair with the attribute
       rattr.  If successful, it returns a malloced copy of the NUL-terminated
       value  associated  with rattr.  If tp is non nil, *tp will point to the
       entry.  Otherwise the entry will be freed.

       Csgetvalue is  like  ndbgetvalue  but  queries  the  connection  server
       instead of looking directly at the database.  Its first argument speci‐
       fies the network root to use.  If the argument is  0,  it  defaults  to
       "/net".

       Ndbfree frees a list of tuples returned by one of the other routines.

       Ipattr takes the name of an IP system and returns the attribute it cor‐
       responds to:

              dom    domain name

              ip     Internet number

              sys    system name

       Ndbgetipaddr looks in db for an entry matching sys as the  value  of  a
       sys=  or  dom= attribute/value pair and returns all IP addresses in the
       entry.  If sys is already an IP address, a tuple containing  just  that
       address is returned.

       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,  attr=val.   Ndbipinfo  returns a list of tuples
       whose attributes match the attributes in the n element array attrs.  If
       any  attrs  begin  with  the  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.

              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

       Calling

              ndbipinfo(db, "dom", "x.big.com", ["bootf" "smtp" "dns"], 3)

       will  return  the  tuples   bootf=/386/9pc,   smtp=smtp1.big.com,   and
       dns=dns.big.com.

       Csipinfo is to ndbipinfo as csgetval is to ndbgetval.

       The  next  three  routines  are  used  by programs that create the hash
       tables and database files.  Ndbhash computes a hash offset into a table
       of  length hlen for the string val.  Ndbparse reads and parses the next
       entry from the database file.  Multiple calls to ndbparse parse sequen‐
       tial entries in the database file.  A zero is returned at end of file.

       Dnsquery  submits  a  query  about domainname to the ndb/dns mounted at
       netroot/dns.  It returns a linked list  of  Ndbtuple's  representing  a
       single  database  entry.   The tuples are logically arranged into lines
       using the line field in the structure.  The possible  type's  of  query
       are and the attributes on each returned tuple line is:

       ip     find the IP addresses.  Returns domain name (dom) and ip address
              (ip)

       mx     look up the mail  exchangers.   Returns  preference  (pref)  and
              exchanger (mx)

       ptr    do  a  reverse  query.   Here  domainname  must  be  an ASCII IP
              address.  Returns reverse name (ptr) and domain name (dom)

       cname  get the system that this name is a nickname  for.   Returns  the
              nickname (dom) and the real name (cname)

       soa    return  the  start  of area record for this field.  Returns area
              name (dom), primary name server (ns),  serial  number  (serial),
              refresh  time  in  seconds  (refresh),  retry  time  in  seconds
              (retry), expiration time in seconds (expire), and  minimum  time
              to lie (ttl).

       ns     name servers.  Returns domain name (dom) and name server (ns)

       Ndbfindattr  searches  entry  for  the  tuple  with  attribute attr and
       returns a pointer to the tuple.  If line points to a particular line in
       the  entry, the search starts there and then wraps around to the begin‐
       ning of the entry.

       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 ndbopen and ndb‐
       parse  and provide its own search routines.  The 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.

       Finally, a number of routines are provided for manipulating tuples.

       Ndbdiscard removes attr/val pair a from tuple t and  frees  it.   If  a
       isn't in t it is just freed.

       Ndbconcatenate  concatenates two tuples and returns the result.  Either
       or both tuples may be nil.

       Ndbreorder reorders a tuple t to make the line containing attr/val pair
       a first in the entry and making a first in its line.

       Ndbsubstitute  replaces  a single att/val pair from in t with the tuple
       to.  All attr/val pairs in to end up on the same line.  from is freed.

       Ndbsetmalloctag sets the malloc tag (see setmalloctag in malloc(2))  of
       each tuple in the list t to tag.

FILES
       /lib/ndb    directory of network database files

SOURCE
       /sys/src/libndb

SEE ALSO
       ndb(6), ndb(8)

DIAGNOSTICS
       Ndbgetvalue,  csgetvalue,  and ndblookvalue set errstr to if the buffer
       provided isn't long enough for the returned value.

BUGS
       Ndbgetval, csgetval, and ndblookval are deprecated versions of  ndbget‐
       value,  csgetvalue, and ndblookvalue.  They expect a fixed 64 byte long
       result buffer and existed when the values of a Ndbtuple structure  were
       fixed length.



                                                                        NDB(2)