3 d93fca6a 2005-02-11 devnull ndbopen, ndbcat, ndbchanged, ndbclose, ndbreopen, ndbsearch, ndbsnext, ndbgetvalue, ndbfree, ipattr, ndbgetipaddr, ndbipinfo, ndbhash, ndbparse, ndbfindattr, ndbdiscard, ndbconcatenate, ndbreorder, ndbsubstitute, ndbgetval, ndblookval \- network database
4 d93fca6a 2005-02-11 devnull .SH SYNOPSIS
5 d93fca6a 2005-02-11 devnull .B #include <u.h>
7 d93fca6a 2005-02-11 devnull .B #include <libc.h>
9 d93fca6a 2005-02-11 devnull .B #include <bio.h>
11 d93fca6a 2005-02-11 devnull .B #include <ndb.h>
12 d93fca6a 2005-02-11 devnull .ta \w'\fLNdbtuplexx 'u
15 d93fca6a 2005-02-11 devnull Ndb* ndbopen(char *file)
18 d93fca6a 2005-02-11 devnull Ndb* ndbcat(Ndb *db1, Ndb *db2)
21 d93fca6a 2005-02-11 devnull Ndb* ndbchanged(Ndb *db)
24 d93fca6a 2005-02-11 devnull int ndbreopen(Ndb *db)
27 d93fca6a 2005-02-11 devnull void ndbclose(Ndb *db)
30 d93fca6a 2005-02-11 devnull Ndbtuple* ndbsearch(Ndb *db, Ndbs *s, char *attr, char *val)
33 d93fca6a 2005-02-11 devnull Ndbtuple* ndbsnext(Ndbs *s, char *attr, char *val)
36 d93fca6a 2005-02-11 devnull char* ndbgetvalue(Ndb *db, Ndbs *s, char *attr, char *val,
39 d93fca6a 2005-02-11 devnull char *rattr, Ndbtuple **tp)
42 d93fca6a 2005-02-11 devnull .\" char* csgetvalue(char *netroot, char *attr, char *val, char *rattr,
43 d93fca6a 2005-02-11 devnull .\" Ndbtuple **tp)
46 d93fca6a 2005-02-11 devnull char* ipattr(char *name)
49 d93fca6a 2005-02-11 devnull Ndbtuple* ndbgetipaddr(Ndb *db, char *sys);
52 d93fca6a 2005-02-11 devnull Ndbtuple* ndbipinfo(Ndb *db, char *attr, char *val, char **attrs,
54 d93fca6a 2005-02-11 devnull .B int nattr)
57 d93fca6a 2005-02-11 devnull .\" Ndbtuple* csipinfo(char *netroot, char *attr, char *val, char **attrs,
59 d93fca6a 2005-02-11 devnull .\" .B int nattr)
62 d93fca6a 2005-02-11 devnull ulong ndbhash(char *val, int hlen)
65 d93fca6a 2005-02-11 devnull Ndbtuple* ndbparse(Ndb *db)
68 d93fca6a 2005-02-11 devnull .\" Ndbtuple* dnsquery(char *netroot, char *domainname, char *type)
71 d93fca6a 2005-02-11 devnull Ndbtuple* ndbfindattr(Ndbtuple *entry, Ndbtuple *line, char *attr)
74 d93fca6a 2005-02-11 devnull void ndbfree(Ndbtuple *db)
77 d93fca6a 2005-02-11 devnull Ndbtuple* ndbdiscard(Ndbtuple *t, Ndbtuple *a)
80 d93fca6a 2005-02-11 devnull Ndbtuple* ndbconcatenate(Ndbtuple *a, Ndbtuple *b);
83 d93fca6a 2005-02-11 devnull Ndbtuple* ndbreorder(Ndbtuple *t, Ndbtuple *a);
86 d93fca6a 2005-02-11 devnull Ndbtuple* ndbsubstitute(Ndbtuple *t, Ndbtuple *from, Ndbtuple *to);
87 d93fca6a 2005-02-11 devnull .SH DESCRIPTION
88 d93fca6a 2005-02-11 devnull These routines are used by network administrative programs to search
89 d93fca6a 2005-02-11 devnull the network database.
90 d93fca6a 2005-02-11 devnull They operate on the database files described in
91 d32deab1 2020-08-16 rsc .MR ndb (7) .
93 d93fca6a 2005-02-11 devnull .I Ndbopen
94 d93fca6a 2005-02-11 devnull opens the database
96 d93fca6a 2005-02-11 devnull and calls
97 d32deab1 2020-08-16 rsc .MR malloc (3)
98 d93fca6a 2005-02-11 devnull to allocate a buffer for it.
101 d93fca6a 2005-02-11 devnull is zero, all network database files are opened.
103 d93fca6a 2005-02-11 devnull .I Ndbcat
104 d93fca6a 2005-02-11 devnull concatenates two open databases. Either argument may be
107 d93fca6a 2005-02-11 devnull .I Ndbreopen
108 d93fca6a 2005-02-11 devnull checks if the database files associated with
110 d93fca6a 2005-02-11 devnull have changed and if so throws out any cached information and reopens
111 d93fca6a 2005-02-11 devnull the files.
113 d93fca6a 2005-02-11 devnull .I Ndbclose
114 d93fca6a 2005-02-11 devnull closes any database files associated with
116 d93fca6a 2005-02-11 devnull and frees all storage associated with them.
118 d93fca6a 2005-02-11 devnull .I Ndbsearch
120 d93fca6a 2005-02-11 devnull .I ndbsnext
121 d93fca6a 2005-02-11 devnull search a database for an entry containing the
122 d93fca6a 2005-02-11 devnull attribute/value pair,
123 d93fca6a 2005-02-11 devnull .IR attr = val .
124 d93fca6a 2005-02-11 devnull .I Ndbsearch
125 d93fca6a 2005-02-11 devnull is used to find the first match and
126 d93fca6a 2005-02-11 devnull .I ndbsnext
127 d93fca6a 2005-02-11 devnull is used to find each successive match.
128 d93fca6a 2005-02-11 devnull On a successful search both return a linked list of
129 d93fca6a 2005-02-11 devnull .I Ndbtuple
130 d93fca6a 2005-02-11 devnull structures acquired by
131 d32deab1 2020-08-16 rsc .MR malloc (3)
132 d93fca6a 2005-02-11 devnull that represent the attribute/value pairs in the
134 d93fca6a 2005-02-11 devnull On failure they return zero.
137 d93fca6a 2005-02-11 devnull typedef struct Ndbtuple Ndbtuple;
138 d93fca6a 2005-02-11 devnull struct Ndbtuple {
139 d93fca6a 2005-02-11 devnull char attr[Ndbalen];
140 d93fca6a 2005-02-11 devnull char *val;
141 d93fca6a 2005-02-11 devnull Ndbtuple *entry;
142 d93fca6a 2005-02-11 devnull Ndbtuple *line;
143 d93fca6a 2005-02-11 devnull ulong ptr; /* for the application; starts 0 */
144 d93fca6a 2005-02-11 devnull char valbuf[Ndbvlen]; /* initial allocation for val */
149 d93fca6a 2005-02-11 devnull .I entry
150 d93fca6a 2005-02-11 devnull pointers chain together all pairs in the entry in a null-terminated list.
153 d93fca6a 2005-02-11 devnull pointers chain together all pairs on the same line
154 d93fca6a 2005-02-11 devnull in a circular list.
155 d93fca6a 2005-02-11 devnull Thus, a program can implement 2 levels of binding for
156 d93fca6a 2005-02-11 devnull pairs in an entry.
157 d93fca6a 2005-02-11 devnull In general, pairs on the same line are bound tighter
158 d93fca6a 2005-02-11 devnull than pairs on different lines.
160 d93fca6a 2005-02-11 devnull The argument
163 d93fca6a 2005-02-11 devnull .I ndbsearch
164 d93fca6a 2005-02-11 devnull has type
166 d93fca6a 2005-02-11 devnull and should be pointed to valid storage before calling
167 d93fca6a 2005-02-11 devnull .IR ndbsearch ,
168 d93fca6a 2005-02-11 devnull which will fill it with information used by
169 d93fca6a 2005-02-11 devnull .I ndbsnext
170 d93fca6a 2005-02-11 devnull to link successive searches.
171 d93fca6a 2005-02-11 devnull The structure
173 d93fca6a 2005-02-11 devnull looks like:
176 d93fca6a 2005-02-11 devnull typedef struct Ndbs Ndbs;
177 d93fca6a 2005-02-11 devnull struct Ndbs {
178 d93fca6a 2005-02-11 devnull Ndb *db; /* data base file being searched */
180 d93fca6a 2005-02-11 devnull Ndbtuple *t; /* last attribute value pair found */
186 d93fca6a 2005-02-11 devnull field points to the pair within the entry matched by the
187 d93fca6a 2005-02-11 devnull .I ndbsearch
189 d93fca6a 2005-02-11 devnull .IR ndbsnext .
191 d93fca6a 2005-02-11 devnull .I Ndbgetvalue
192 d93fca6a 2005-02-11 devnull searches the database for an entry containing not only an
193 d93fca6a 2005-02-11 devnull attribute/value pair,
194 d93fca6a 2005-02-11 devnull .IR attr = val ,
195 d93fca6a 2005-02-11 devnull but also a pair with the attribute
196 d93fca6a 2005-02-11 devnull .IR rattr .
197 d93fca6a 2005-02-11 devnull If successful, it returns a malloced copy of the null terminated value associated with
198 d93fca6a 2005-02-11 devnull .IR rattr .
201 d93fca6a 2005-02-11 devnull is non nil,
203 d93fca6a 2005-02-11 devnull will point to the entry. Otherwise the entry will be freeed.
205 d93fca6a 2005-02-11 devnull .\" .I Csgetvalue
206 d93fca6a 2005-02-11 devnull .\" is like
207 d93fca6a 2005-02-11 devnull .\" .I ndbgetvalue
208 d93fca6a 2005-02-11 devnull .\" but queries the connection server
209 d93fca6a 2005-02-11 devnull .\" instead of looking directly at the database.
210 d93fca6a 2005-02-11 devnull .\" Its first argument specifies the network root to use.
211 d93fca6a 2005-02-11 devnull .\" If the argument is 0, it defaults to
212 d93fca6a 2005-02-11 devnull .\" \f5"/net"\f1.
214 d93fca6a 2005-02-11 devnull .I Ndbfree
215 d93fca6a 2005-02-11 devnull frees a list of tuples returned by one of the other
216 d93fca6a 2005-02-11 devnull routines.
218 d93fca6a 2005-02-11 devnull .I Ipattr
219 d93fca6a 2005-02-11 devnull takes the name of an IP system and returns the attribute
220 d93fca6a 2005-02-11 devnull it corresponds to:
224 d93fca6a 2005-02-11 devnull domain name
227 d93fca6a 2005-02-11 devnull Internet number
230 d93fca6a 2005-02-11 devnull system name
233 d93fca6a 2005-02-11 devnull .I Ndbgetipaddr
234 d93fca6a 2005-02-11 devnull looks in
236 d93fca6a 2005-02-11 devnull for an entry matching
238 d93fca6a 2005-02-11 devnull as the value of a
242 d93fca6a 2005-02-11 devnull attribute/value pair and returns all IP addresses in the entry.
245 d93fca6a 2005-02-11 devnull is already an IP address, a tuple containing just
246 d93fca6a 2005-02-11 devnull that address is returned.
248 d93fca6a 2005-02-11 devnull .I Ndbipinfo
249 d93fca6a 2005-02-11 devnull looks up Internet protocol information about a system.
250 d93fca6a 2005-02-11 devnull This is an IP aware search. It looks first for information
251 d93fca6a 2005-02-11 devnull in the system's database entry and then in the database entries
252 d93fca6a 2005-02-11 devnull for any IP subnets or networks containing the system.
253 d93fca6a 2005-02-11 devnull The system is identified by the
254 d93fca6a 2005-02-11 devnull attribute/value pair,
255 d93fca6a 2005-02-11 devnull .IR attr = val .
256 d93fca6a 2005-02-11 devnull .I Ndbipinfo
257 d93fca6a 2005-02-11 devnull returns a list of tuples whose attributes match the
258 d93fca6a 2005-02-11 devnull attributes in the
260 d93fca6a 2005-02-11 devnull element array
261 d93fca6a 2005-02-11 devnull .IR attrs .
262 d93fca6a 2005-02-11 devnull For example, consider the following database entries describing a network,
263 d93fca6a 2005-02-11 devnull a subnetwork, and a system.
266 d93fca6a 2005-02-11 devnull ipnet=big ip=10.0.0.0
267 d93fca6a 2005-02-11 devnull dns=dns.big.com
268 d93fca6a 2005-02-11 devnull smtp=smtp.big.com
269 d93fca6a 2005-02-11 devnull ipnet=dept ip=10.1.1.0 ipmask=255.255.255.0
270 d93fca6a 2005-02-11 devnull smtp=smtp1.big.com
271 d93fca6a 2005-02-11 devnull ip=10.1.1.4 dom=x.big.com
272 d93fca6a 2005-02-11 devnull bootf=/386/9pc
278 d93fca6a 2005-02-11 devnull ndbipinfo(db, "dom", "x.big.com", ["bootf" "smtp" "dns"], 3)
281 d93fca6a 2005-02-11 devnull will return the tuples
282 d93fca6a 2005-02-11 devnull .BR bootf=/386/9pc ,
283 d93fca6a 2005-02-11 devnull .BR smtp=smtp1.big.com ,
285 d93fca6a 2005-02-11 devnull .BR dns=dns.big.com .
287 d93fca6a 2005-02-11 devnull .\" .I Csipinfo
288 d93fca6a 2005-02-11 devnull .\" is to
289 d93fca6a 2005-02-11 devnull .\" .I ndbipinfo
291 d93fca6a 2005-02-11 devnull .\" .I csgetval
292 d93fca6a 2005-02-11 devnull .\" is to
293 d93fca6a 2005-02-11 devnull .\" .IR ndbgetval .
295 d93fca6a 2005-02-11 devnull The next three routines are used by programs that create the
296 d93fca6a 2005-02-11 devnull hash tables and database files.
297 d93fca6a 2005-02-11 devnull .I Ndbhash
298 d93fca6a 2005-02-11 devnull computes a hash offset into a table of length
300 d93fca6a 2005-02-11 devnull for the string
301 d93fca6a 2005-02-11 devnull .IR val .
302 d93fca6a 2005-02-11 devnull .I Ndbparse
303 d93fca6a 2005-02-11 devnull reads and parses the next entry from the database file.
304 d93fca6a 2005-02-11 devnull Multiple calls to
305 d93fca6a 2005-02-11 devnull .IR ndbparse
306 d93fca6a 2005-02-11 devnull parse sequential entries in the database file.
307 d93fca6a 2005-02-11 devnull A zero is returned at end of file.
309 d93fca6a 2005-02-11 devnull .\" .I Dnsquery
310 d93fca6a 2005-02-11 devnull .\" submits a query about
311 d93fca6a 2005-02-11 devnull .\" .I domainname
312 d93fca6a 2005-02-11 devnull .\" to the
313 d93fca6a 2005-02-11 devnull .\" .I ndb/dns
314 d93fca6a 2005-02-11 devnull .\" mounted at
315 d93fca6a 2005-02-11 devnull .\" .IB netroot /dns.
316 d93fca6a 2005-02-11 devnull .\" It returns a linked list of
317 d93fca6a 2005-02-11 devnull .\" .I Ndbtuple's
318 d93fca6a 2005-02-11 devnull .\" representing a single database entry.
319 d93fca6a 2005-02-11 devnull .\" The tuples are logicly arranged into lines using the
320 d93fca6a 2005-02-11 devnull .\" .B line
321 d93fca6a 2005-02-11 devnull .\" fieldin the structure.
322 d93fca6a 2005-02-11 devnull .\" The possible
323 d93fca6a 2005-02-11 devnull .\" .IR type 's
324 d93fca6a 2005-02-11 devnull .\" of query are and the attributes on each returned tuple line is:
326 d93fca6a 2005-02-11 devnull .\" .B ip
327 d93fca6a 2005-02-11 devnull .\" find the IP addresses. Returns
328 d93fca6a 2005-02-11 devnull .\" domain name
329 d93fca6a 2005-02-11 devnull .\" .RI ( dom )
330 d93fca6a 2005-02-11 devnull .\" and ip address
331 d93fca6a 2005-02-11 devnull .\" .RI ( ip )
333 d93fca6a 2005-02-11 devnull .\" .B mx
334 d93fca6a 2005-02-11 devnull .\" look up the mail exchangers. Returns preference
335 d93fca6a 2005-02-11 devnull .\" .RI ( pref )
336 d93fca6a 2005-02-11 devnull .\" and exchanger
337 d93fca6a 2005-02-11 devnull .\" .RI ( mx )
339 d93fca6a 2005-02-11 devnull .\" .B ptr
340 d93fca6a 2005-02-11 devnull .\" do a reverse query. Here
341 d93fca6a 2005-02-11 devnull .\" .I domainname
342 d93fca6a 2005-02-11 devnull .\" must be an
343 d93fca6a 2005-02-11 devnull .\" .SM ASCII
344 d93fca6a 2005-02-11 devnull .\" IP address. Returns reverse name
345 d93fca6a 2005-02-11 devnull .\" .RI ( ptr )
346 d93fca6a 2005-02-11 devnull .\" and domain name
347 d93fca6a 2005-02-11 devnull .\" .RI ( dom )
349 d93fca6a 2005-02-11 devnull .\" .B cname
350 d93fca6a 2005-02-11 devnull .\" get the system that this name is a nickname for. Returns the nickname
351 d93fca6a 2005-02-11 devnull .\" .RI ( dom )
352 d93fca6a 2005-02-11 devnull .\" and the real name
353 d93fca6a 2005-02-11 devnull .\" .RI ( cname )
355 d93fca6a 2005-02-11 devnull .\" .B soa
356 d93fca6a 2005-02-11 devnull .\" return the start of area record for this field. Returns
357 d93fca6a 2005-02-11 devnull .\" area name
358 d93fca6a 2005-02-11 devnull .\" .RI ( dom ),
359 d93fca6a 2005-02-11 devnull .\" primary name server
360 d93fca6a 2005-02-11 devnull .\" .RI ( ns ),
361 d93fca6a 2005-02-11 devnull .\" serial number
362 d93fca6a 2005-02-11 devnull .\" .RI ( serial ),
363 d93fca6a 2005-02-11 devnull .\" refresh time in seconds
364 d93fca6a 2005-02-11 devnull .\" .RI ( refresh ),
365 d93fca6a 2005-02-11 devnull .\" retry time in seconds
366 d93fca6a 2005-02-11 devnull .\" .RI ( retry ),
367 d93fca6a 2005-02-11 devnull .\" expiration time in seconds
368 d93fca6a 2005-02-11 devnull .\" .RI ( expire ),
369 d93fca6a 2005-02-11 devnull .\" and minimum time to lie
370 d93fca6a 2005-02-11 devnull .\" .RI ( ttl ).
372 d93fca6a 2005-02-11 devnull .\" .B ns
373 d93fca6a 2005-02-11 devnull .\" name servers. Returns domain name
374 d93fca6a 2005-02-11 devnull .\" .RI ( dom )
375 d93fca6a 2005-02-11 devnull .\" and name server
376 d93fca6a 2005-02-11 devnull .\" .RI ( ns )
378 d93fca6a 2005-02-11 devnull .I Ndbfindattr
379 d93fca6a 2005-02-11 devnull searches
380 d93fca6a 2005-02-11 devnull .I entry
381 d93fca6a 2005-02-11 devnull for the tuple
382 d93fca6a 2005-02-11 devnull with attribute
384 d93fca6a 2005-02-11 devnull and returns a pointer to the tuple.
387 d93fca6a 2005-02-11 devnull points to a particular line in the entry, the
388 d93fca6a 2005-02-11 devnull search starts there and then wraps around to the beginning
389 d93fca6a 2005-02-11 devnull of the entry.
391 d93fca6a 2005-02-11 devnull All of the routines provided to search the database
392 d93fca6a 2005-02-11 devnull provide an always consistent view of the relevant
393 d93fca6a 2005-02-11 devnull files. However, it may be advantageous for an application
394 d93fca6a 2005-02-11 devnull to read in the whole database using
395 d93fca6a 2005-02-11 devnull .I ndbopen
397 d93fca6a 2005-02-11 devnull .I ndbparse
398 d93fca6a 2005-02-11 devnull and provide its own search routines. The
399 d93fca6a 2005-02-11 devnull .I ndbchanged
400 d93fca6a 2005-02-11 devnull routine can be used by the application to periodicly
401 d93fca6a 2005-02-11 devnull check for changes. It returns zero
402 d93fca6a 2005-02-11 devnull if none of the files comprising the database have
403 d93fca6a 2005-02-11 devnull changes and non-zero if they have.
405 d93fca6a 2005-02-11 devnull Finally, a number of routines are provided for manipulating
408 d93fca6a 2005-02-11 devnull .I Ndbdiscard
409 d93fca6a 2005-02-11 devnull removes attr/val pair
411 d93fca6a 2005-02-11 devnull from tuple
413 d93fca6a 2005-02-11 devnull and frees it.
416 d93fca6a 2005-02-11 devnull isn't in
418 d93fca6a 2005-02-11 devnull it is just freed.
420 d93fca6a 2005-02-11 devnull .I Ndbconcatenate
421 d93fca6a 2005-02-11 devnull concatenates two tuples and returns the result. Either
422 d93fca6a 2005-02-11 devnull or both tuples may be nil.
424 d93fca6a 2005-02-11 devnull .I Ndbreorder
425 d93fca6a 2005-02-11 devnull reorders a tuple
427 d93fca6a 2005-02-11 devnull to make the line containing attr/val pair
429 d93fca6a 2005-02-11 devnull first in the entry and making
431 d93fca6a 2005-02-11 devnull first in its line.
433 d93fca6a 2005-02-11 devnull .I Ndbsubstitute
434 d93fca6a 2005-02-11 devnull replaces a single att/val pair
438 d93fca6a 2005-02-11 devnull with the tuple
439 d93fca6a 2005-02-11 devnull .IR to .
440 d93fca6a 2005-02-11 devnull All attr/val pairs in
442 d93fca6a 2005-02-11 devnull end up on the same line.
444 d93fca6a 2005-02-11 devnull is freed.
445 d93fca6a 2005-02-11 devnull .SH FILES
447 d93fca6a 2005-02-11 devnull .B \*9/ndb
448 d93fca6a 2005-02-11 devnull directory of network database files
450 d93fca6a 2005-02-11 devnull .SH SOURCE
451 d93fca6a 2005-02-11 devnull .B \*9/src/libndb
452 d93fca6a 2005-02-11 devnull .SH SEE ALSO
455 d93fca6a 2005-02-11 devnull .SH DIAGNOSTICS
456 d93fca6a 2005-02-11 devnull .IR Ndbgetvalue
458 d93fca6a 2005-02-11 devnull .I ndblookvalue
460 d93fca6a 2005-02-11 devnull .I errstr
462 d93fca6a 2005-02-11 devnull .B "buffer too short"
463 d93fca6a 2005-02-11 devnull if the buffer provided isn't long enough for the
464 d93fca6a 2005-02-11 devnull returned value.
465 d93fca6a 2005-02-11 devnull .SH BUGS
466 d93fca6a 2005-02-11 devnull .IR Ndbgetval
468 d93fca6a 2005-02-11 devnull .I ndblookval
469 d93fca6a 2005-02-11 devnull are deprecated versions of
470 d93fca6a 2005-02-11 devnull .IR ndbgetvalue
472 d93fca6a 2005-02-11 devnull .IR ndblookvalue .
473 d93fca6a 2005-02-11 devnull They expect a fixed 64 byte long result
474 d93fca6a 2005-02-11 devnull buffer and existed when the values of a
475 d93fca6a 2005-02-11 devnull .I Ndbtuple
476 d93fca6a 2005-02-11 devnull structure where fixed length.
