dots

Personal dotfiles
git clone git://git.gormless.xyz/dots.git
Log | Files | Refs

ndb.html (18757B)


      1 <head>
      2 <title>ndb(3) - Plan 9 from User Space</title>
      3 <meta content="text/html; charset=utf-8" http-equiv=Content-Type>
      4 </head>
      5 <body bgcolor=#ffffff>
      6 <table border=0 cellpadding=0 cellspacing=0 width=100%>
      7 <tr height=10><td>
      8 <tr><td width=20><td>
      9 <tr><td width=20><td><b>NDB(3)</b><td align=right><b>NDB(3)</b>
     10 <tr><td width=20><td colspan=2>
     11     <br>
     12 <p><font size=+1><b>NAME     </b></font><br>
     13 
     14 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     15 
     16     ndbopen, ndbcat, ndbchanged, ndbclose, ndbreopen, ndbsearch, ndbsnext,
     17     ndbgetvalue, ndbfree, ipattr, ndbgetipaddr, ndbipinfo, ndbhash,
     18     ndbparse, ndbfindattr, ndbdiscard, ndbconcatenate, ndbreorder,
     19     ndbsubstitute, ndbgetval, ndblookval &ndash; network database<br>
     20     
     21 </table>
     22 <p><font size=+1><b>SYNOPSIS     </b></font><br>
     23 
     24 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     25 
     26     <tt><font size=+1>#include &lt;u.h&gt;<br>
     27     #include &lt;libc.h&gt;<br>
     28     #include &lt;bio.h&gt;<br>
     29     #include &lt;ndb.h&gt; 
     30     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     31     </font></tt>
     32     <tt><font size=+1>Ndb* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ndbopen(char *file) 
     33     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     34     </font></tt>
     35     <tt><font size=+1>Ndb* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ndbcat(Ndb *db1, Ndb *db2) 
     36     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     37     </font></tt>
     38     <tt><font size=+1>Ndb* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ndbchanged(Ndb *db) 
     39     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     40     </font></tt>
     41     <tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ndbreopen(Ndb *db) 
     42     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     43     </font></tt>
     44     <tt><font size=+1>void &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ndbclose(Ndb *db) 
     45     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     46     </font></tt>
     47     <tt><font size=+1>Ndbtuple* &nbsp;&nbsp;&nbsp;ndbsearch(Ndb *db, Ndbs *s, char *attr, char *val) 
     48     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     49     </font></tt>
     50     <tt><font size=+1>Ndbtuple* &nbsp;&nbsp;&nbsp;ndbsnext(Ndbs *s, char *attr, char *val) 
     51     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     52     </font></tt>
     53     <tt><font size=+1>char* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ndbgetvalue(Ndb *db, Ndbs *s, char *attr, char *val,<br>
     54     
     55     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     56 
     57         
     58         <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     59 
     60             char *rattr, Ndbtuple **tp) 
     61             <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     62             
     63         </table>
     64         
     65     </table>
     66     </font></tt>
     67     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     68 
     69         
     70         <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     71 
     72             
     73             
     74         </table>
     75         
     76     </table>
     77     <tt><font size=+1>char* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ipattr(char *name) 
     78     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     79     </font></tt>
     80     <tt><font size=+1>Ndbtuple* &nbsp;&nbsp;&nbsp;ndbgetipaddr(Ndb *db, char *sys); 
     81     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     82     </font></tt>
     83     <tt><font size=+1>Ndbtuple* &nbsp;&nbsp;&nbsp;ndbipinfo(Ndb *db, char *attr, char *val, char **attrs,<br>
     84     
     85     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     86 
     87         
     88         <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     89 
     90             int nattr) 
     91             <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     92             
     93         </table>
     94         
     95     </table>
     96     </font></tt>
     97     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     98 
     99         
    100         <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    101 
    102             
    103             
    104         </table>
    105         
    106     </table>
    107     <tt><font size=+1>ulong &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ndbhash(char *val, int hlen) 
    108     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    109     </font></tt>
    110     <tt><font size=+1>Ndbtuple* &nbsp;&nbsp;&nbsp;ndbparse(Ndb *db) 
    111     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    112     </font></tt>
    113     <tt><font size=+1>Ndbtuple* &nbsp;&nbsp;&nbsp;ndbfindattr(Ndbtuple *entry, Ndbtuple *line, char *attr)
    114     
    115     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    116     </font></tt>
    117     <tt><font size=+1>void &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ndbfree(Ndbtuple *db) 
    118     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    119     </font></tt>
    120     <tt><font size=+1>Ndbtuple* &nbsp;&nbsp;&nbsp;ndbdiscard(Ndbtuple &nbsp;&nbsp;&nbsp;*t, Ndbtuple *a) 
    121     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    122     </font></tt>
    123     <tt><font size=+1>Ndbtuple* &nbsp;&nbsp;&nbsp;ndbconcatenate(Ndbtuple *a, Ndbtuple *b); 
    124     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    125     </font></tt>
    126     <tt><font size=+1>Ndbtuple* &nbsp;&nbsp;&nbsp;ndbreorder(Ndbtuple *t, Ndbtuple *a); 
    127     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    128     </font></tt>
    129     <tt><font size=+1>Ndbtuple* &nbsp;&nbsp;&nbsp;ndbsubstitute(Ndbtuple *t, Ndbtuple *from, Ndbtuple
    130     *to);<br>
    131     </font></tt>
    132 </table>
    133 <p><font size=+1><b>DESCRIPTION     </b></font><br>
    134 
    135 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    136 
    137     These routines are used by network administrative programs to
    138     search the network database. They operate on the database files
    139     described in <a href="../man7/ndb.html"><i>ndb</i>(7)</a>. 
    140     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    141     
    142     <i>Ndbopen</i> opens the database <i>file</i> and calls <i>malloc</i>(3) to allocate
    143     a buffer for it. If <i>file</i> is zero, all network database files are
    144     opened. 
    145     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    146     
    147     <i>Ndbcat</i> concatenates two open databases. Either argument may be
    148     nil. 
    149     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    150     
    151     <i>Ndbreopen</i> checks if the database files associated with <i>db</i> have
    152     changed and if so throws out any cached information and reopens
    153     the files. 
    154     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    155     
    156     <i>Ndbclose</i> closes any database files associated with <i>db</i> and frees
    157     all storage associated with them. 
    158     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    159     
    160     <i>Ndbsearch</i> and <i>ndbsnext</i> search a database for an entry containing
    161     the attribute/value pair, <i>attr</i>=<i>val</i>. <i>Ndbsearch</i> is used to find
    162     the first match and <i>ndbsnext</i> is used to find each successive match.
    163     On a successful search both return a linked list of <i>Ndbtuple</i> structures
    164     acquired by <i>malloc</i>(3) that represent the attribute/value pairs
    165     in the entry. On failure
    166     they return zero.<br>
    167     
    168     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    169 
    170         <tt><font size=+1>typedef struct Ndbtuple Ndbtuple;<br>
    171         struct Ndbtuple {<br>
    172          
    173         <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    174 
    175             char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;attr[Ndbalen];<br>
    176              char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*val;<br>
    177              Ndbtuple &nbsp;&nbsp;&nbsp;*entry;<br>
    178              Ndbtuple &nbsp;&nbsp;&nbsp;*line;<br>
    179              ulong &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ptr; &nbsp;&nbsp;&nbsp;&nbsp;/* for the application; starts 0 */<br>
    180              char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;valbuf[Ndbvlen]; &nbsp;&nbsp;&nbsp;/* initial allocation for val */<br>
    181             
    182         </table>
    183         };<br>
    184         
    185         <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    186         </font></tt>
    187         
    188     </table>
    189     The <i>entry</i> pointers chain together all pairs in the entry in a
    190     null-terminated list. The <i>line</i> pointers chain together all pairs
    191     on the same line in a circular list. Thus, a program can implement
    192     2 levels of binding for pairs in an entry. In general, pairs on
    193     the same line are bound tighter than pairs on different lines.
    194     
    195     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    196     
    197     The argument <i>s</i> of <i>ndbsearch</i> has type <i>Ndbs</i> and should be pointed
    198     to valid storage before calling <i>ndbsearch</i>, which will fill it
    199     with information used by <i>ndbsnext</i> to link successive searches.
    200     The structure <i>Ndbs</i> looks like:<br>
    201     
    202     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    203 
    204         <tt><font size=+1>typedef struct Ndbs Ndbs;<br>
    205         struct Ndbs {<br>
    206          
    207         <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    208 
    209             Ndb &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*db; &nbsp;&nbsp;&nbsp;/* data base file being searched */<br>
    210              ...<br>
    211              Ndbtuple *t; &nbsp;&nbsp;&nbsp;&nbsp;/* last attribute value pair found */<br>
    212             
    213         </table>
    214         };<br>
    215         
    216         <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    217         </font></tt>
    218         
    219     </table>
    220     The <i>t</i> field points to the pair within the entry matched by the
    221     <i>ndbsearch</i> or <i>ndbsnext</i>. 
    222     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    223     
    224     <i>Ndbgetvalue</i> searches the database for an entry containing not
    225     only an attribute/value pair, <i>attr</i>=<i>val</i>, but also a pair with the
    226     attribute <i>rattr</i>. If successful, it returns a malloced copy of
    227     the null terminated value associated with <i>rattr</i>. If <i>tp</i> is non
    228     nil, <i>*tp</i> will point to the entry. Otherwise the entry will be
    229     freeed. 
    230     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    231     
    232     <i>Ndbfree</i> frees a list of tuples returned by one of the other routines.
    233     
    234     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    235     
    236     <i>Ipattr</i> takes the name of an IP system and returns the attribute
    237     it corresponds to:<br>
    238     
    239     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    240 
    241         <tt><font size=+1>dom</font></tt>&nbsp;&nbsp;&nbsp;domain name<br>
    242         <tt><font size=+1>ip</font></tt>&nbsp;&nbsp;&nbsp;&nbsp;Internet number<br>
    243         <tt><font size=+1>sys</font></tt>&nbsp;&nbsp;&nbsp;system name<br>
    244         
    245         <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    246         
    247         
    248     </table>
    249     <i>Ndbgetipaddr</i> looks in <i>db</i> for an entry matching <i>sys</i> as the value
    250     of a <tt><font size=+1>sys=</font></tt> or <tt><font size=+1>dom=</font></tt> attribute/value pair and returns all IP addresses
    251     in the entry. If <i>sys</i> is already an IP address, a tuple containing
    252     just that address is returned. 
    253     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    254     
    255     <i>Ndbipinfo</i> looks up Internet protocol information about a system.
    256     This is an IP aware search. It looks first for information in
    257     the system&#8217;s database entry and then in the database entries for
    258     any IP subnets or networks containing the system. The system is
    259     identified by the attribute/value pair, <i>attr</i>=<i>val</i>. <i>Ndbipinfo</i> returns
    260     a list of tuples whose attributes
    261     match the attributes in the <i>n</i> element array <i>attrs</i>. For example,
    262     consider the following database entries describing a network,
    263     a subnetwork, and a system. 
    264     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    265     
    266     <tt><font size=+1>ipnet=big ip=10.0.0.0<br>
    267     
    268     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    269 
    270         
    271         <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    272 
    273             dns=dns.big.com<br>
    274             smtp=smtp.big.com<br>
    275             
    276         </table>
    277         
    278     </table>
    279     ipnet=dept ip=10.1.1.0 ipmask=255.255.255.0<br>
    280     
    281     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    282 
    283         
    284         <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    285 
    286             smtp=smtp1.big.com<br>
    287             
    288         </table>
    289         
    290     </table>
    291     ip=10.1.1.4 dom=x.big.com<br>
    292     
    293     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    294 
    295         
    296         <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    297 
    298             bootf=/386/9pc<br>
    299             
    300             <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    301             
    302         </table>
    303         
    304     </table>
    305     </font></tt>
    306     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    307 
    308         
    309         <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    310 
    311             
    312             
    313         </table>
    314         
    315     </table>
    316     Calling 
    317     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    318     
    319      
    320     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    321 
    322         <tt><font size=+1>ndbipinfo(db, &quot;dom&quot;, &quot;x.big.com&quot;, [&quot;bootf&quot; &quot;smtp&quot; &quot;dns&quot;], 3)<br>
    323         
    324         <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    325         </font></tt>
    326         
    327     </table>
    328     will return the tuples <tt><font size=+1>bootf=/386/9pc</font></tt>, <tt><font size=+1>smtp=smtp1.big.com</font></tt>, and
    329     <tt><font size=+1>dns=dns.big.com</font></tt>. 
    330     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    331     
    332     The next three routines are used by programs that create the hash
    333     tables and database files. <i>Ndbhash</i> computes a hash offset into
    334     a table of length <i>hlen</i> for the string <i>val</i>. <i>Ndbparse</i> reads and
    335     parses the next entry from the database file. Multiple calls to
    336     <i>ndbparse</i> parse sequential entries in the database file. A zero
    337     is returned at end of file. 
    338     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    339     
    340     <i>Ndbfindattr</i> searches <i>entry</i> for the tuple with attribute <i>attr</i> and
    341     returns a pointer to the tuple. If <i>line</i> points to a particular
    342     line in the entry, the search starts there and then wraps around
    343     to the beginning of the entry. 
    344     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    345     
    346     All of the routines provided to search the database provide an
    347     always consistent view of the relevant files. However, it may
    348     be advantageous for an application to read in the whole database
    349     using <i>ndbopen</i> and <i>ndbparse</i> and provide its own search routines.
    350     The <i>ndbchanged</i> routine can be used by the application to periodicly
    351     check for changes. It
    352     returns zero if none of the files comprising the database have
    353     changes and non-zero if they have. 
    354     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    355     
    356     Finally, a number of routines are provided for manipulating tuples.
    357     
    358     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    359     
    360     <i>Ndbdiscard</i> removes attr/val pair <i>a</i> from tuple <i>t</i> and frees it.
    361     If <i>a</i> isn&#8217;t in <i>t</i> it is just freed. 
    362     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    363     
    364     <i>Ndbconcatenate</i> concatenates two tuples and returns the result.
    365     Either or both tuples may be nil. 
    366     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    367     
    368     <i>Ndbreorder</i> reorders a tuple <i>t</i> to make the line containing attr/val
    369     pair <i>a</i> first in the entry and making <i>a</i> first in its line. 
    370     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    371     
    372     <i>Ndbsubstitute</i> replaces a single att/val pair <i>from</i> in <i>t</i> with the
    373     tuple <i>to</i>. All attr/val pairs in <i>to</i> end up on the same line. <i>from</i>
    374     is freed.<br>
    375     
    376 </table>
    377 <p><font size=+1><b>FILES     </b></font><br>
    378 
    379 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    380 
    381     <tt><font size=+1><a href="/var/usrlocal/plan9/ndb">/var/usrlocal/plan9/ndb</a><br>
    382     </font></tt>
    383     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    384 
    385         directory of network database files<br>
    386         
    387     </table>
    388     
    389 </table>
    390 <p><font size=+1><b>SOURCE     </b></font><br>
    391 
    392 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    393 
    394     <tt><font size=+1><a href="/var/usrlocal/plan9/src/libndb">/var/usrlocal/plan9/src/libndb</a><br>
    395     </font></tt>
    396 </table>
    397 <p><font size=+1><b>SEE ALSO    </b></font><br>
    398 
    399 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    400 
    401     <a href="../man1/ndb.html"><i>ndb</i>(1)</a> <a href="../man7/ndb.html"><i>ndb</i>(7)</a><br>
    402     
    403 </table>
    404 <p><font size=+1><b>DIAGNOSTICS     </b></font><br>
    405 
    406 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    407 
    408     <i>Ndbgetvalue</i> and <i>ndblookvalue</i> set <i>errstr</i> to <tt><font size=+1>buffer too short</font></tt> if
    409     the buffer provided isn&#8217;t long enough for the returned value.<br>
    410     
    411 </table>
    412 <p><font size=+1><b>BUGS     </b></font><br>
    413 
    414 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    415 
    416     <i>Ndbgetval</i> and <i>ndblookval</i> are deprecated versions of <i>ndbgetvalue</i>
    417     and <i>ndblookvalue</i>. They expect a fixed 64 byte long result buffer
    418     and existed when the values of a <i>Ndbtuple</i> structure where fixed
    419     length.<br>
    420     
    421 </table>
    422 
    423 <td width=20>
    424 <tr height=20><td>
    425 </table>
    426 <!-- TRAILER -->
    427 <table border=0 cellpadding=0 cellspacing=0 width=100%>
    428 <tr height=15><td width=10><td><td width=10>
    429 <tr><td><td>
    430 <center>
    431 <a href="https://9fans.github.io/plan9port/"><img src="../../dist/glendacircle.png" alt="Space Glenda" border=0></a>
    432 </center>
    433 </table>
    434 <!-- TRAILER -->
    435 </body></html>