tndb.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tndb.3 (9722B)
---
1 .TH NDB 3
2 .SH NAME
3 ndbopen, ndbcat, ndbchanged, ndbclose, ndbreopen, ndbsearch, ndbsnext, ndbgetvalue, ndbfree, ipattr, ndbgetipaddr, ndbipinfo, ndbhash, ndbparse, ndbfindattr, ndbdiscard, ndbconcatenate, ndbreorder, ndbsubstitute, ndbgetval, ndblookval \- network database
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .br
9 .B #include <bio.h>
10 .br
11 .B #include <ndb.h>
12 .ta \w'\fLNdbtuplexx 'u
13 .PP
14 .B
15 Ndb* ndbopen(char *file)
16 .PP
17 .B
18 Ndb* ndbcat(Ndb *db1, Ndb *db2)
19 .PP
20 .B
21 Ndb* ndbchanged(Ndb *db)
22 .PP
23 .B
24 int ndbreopen(Ndb *db)
25 .PP
26 .B
27 void ndbclose(Ndb *db)
28 .PP
29 .B
30 Ndbtuple* ndbsearch(Ndb *db, Ndbs *s, char *attr, char *val)
31 .PP
32 .B
33 Ndbtuple* ndbsnext(Ndbs *s, char *attr, char *val)
34 .PP
35 .B
36 char* ndbgetvalue(Ndb *db, Ndbs *s, char *attr, char *val,
37 .br
38 .B
39 char *rattr, Ndbtuple **tp)
40 .\" .PP
41 .\" .B
42 .\" char* csgetvalue(char *netroot, char *attr, char *val, char *rattr,
43 .\" Ndbtuple **tp)
44 .PP
45 .B
46 char* ipattr(char *name)
47 .PP
48 .B
49 Ndbtuple* ndbgetipaddr(Ndb *db, char *sys);
50 .PP
51 .B
52 Ndbtuple* ndbipinfo(Ndb *db, char *attr, char *val, char **attrs,
53 .br
54 .B int nattr)
55 .\" .PP
56 .\" .B
57 .\" Ndbtuple* csipinfo(char *netroot, char *attr, char *val, char **attrs,
58 .\" .br
59 .\" .B int nattr)
60 .PP
61 .B
62 ulong ndbhash(char *val, int hlen)
63 .PP
64 .B
65 Ndbtuple* ndbparse(Ndb *db)
66 .\" .PP
67 .\" .B
68 .\" Ndbtuple* dnsquery(char *netroot, char *domainname, char *type)
69 .PP
70 .B
71 Ndbtuple* ndbfindattr(Ndbtuple *entry, Ndbtuple *line, char *attr)
72 .PP
73 .B
74 void ndbfree(Ndbtuple *db)
75 .PP
76 .B
77 Ndbtuple* ndbdiscard(Ndbtuple *t, Ndbtuple *a)
78 .PP
79 .B
80 Ndbtuple* ndbconcatenate(Ndbtuple *a, Ndbtuple *b);
81 .PP
82 .B
83 Ndbtuple* ndbreorder(Ndbtuple *t, Ndbtuple *a);
84 .PP
85 .B
86 Ndbtuple* ndbsubstitute(Ndbtuple *t, Ndbtuple *from, Ndbtuple *to);
87 .SH DESCRIPTION
88 These routines are used by network administrative programs to search
89 the network database.
90 They operate on the database files described in
91 .MR ndb (7) .
92 .PP
93 .I Ndbopen
94 opens the database
95 .I file
96 and calls
97 .MR malloc (3)
98 to allocate a buffer for it.
99 If
100 .I file
101 is zero, all network database files are opened.
102 .PP
103 .I Ndbcat
104 concatenates two open databases. Either argument may be
105 nil.
106 .PP
107 .I Ndbreopen
108 checks if the database files associated with
109 .I db
110 have changed and if so throws out any cached information and reopens
111 the files.
112 .PP
113 .I Ndbclose
114 closes any database files associated with
115 .I db
116 and frees all storage associated with them.
117 .PP
118 .I Ndbsearch
119 and
120 .I ndbsnext
121 search a database for an entry containing the
122 attribute/value pair,
123 .IR attr = val .
124 .I Ndbsearch
125 is used to find the first match and
126 .I ndbsnext
127 is used to find each successive match.
128 On a successful search both return a linked list of
129 .I Ndbtuple
130 structures acquired by
131 .MR malloc (3)
132 that represent the attribute/value pairs in the
133 entry.
134 On failure they return zero.
135 .IP
136 .EX
137 typedef struct Ndbtuple Ndbtuple;
138 struct Ndbtuple {
139 char attr[Ndbalen];
140 char *val;
141 Ndbtuple *entry;
142 Ndbtuple *line;
143 ulong ptr; /* for the application; starts 0 */
144 char valbuf[Ndbvlen]; /* initial allocation for val */
145 };
146 .EE
147 .LP
148 The
149 .I entry
150 pointers chain together all pairs in the entry in a null-terminated list.
151 The
152 .I line
153 pointers chain together all pairs on the same line
154 in a circular list.
155 Thus, a program can implement 2 levels of binding for
156 pairs in an entry.
157 In general, pairs on the same line are bound tighter
158 than pairs on different lines.
159 .PP
160 The argument
161 .I s
162 of
163 .I ndbsearch
164 has type
165 .I Ndbs
166 and should be pointed to valid storage before calling
167 .IR ndbsearch ,
168 which will fill it with information used by
169 .I ndbsnext
170 to link successive searches.
171 The structure
172 .I Ndbs
173 looks like:
174 .IP
175 .EX
176 typedef struct Ndbs Ndbs;
177 struct Ndbs {
178 Ndb *db; /* data base file being searched */
179 ...
180 Ndbtuple *t; /* last attribute value pair found */
181 };
182 .EE
183 .LP
184 The
185 .I t
186 field points to the pair within the entry matched by the
187 .I ndbsearch
188 or
189 .IR ndbsnext .
190 .PP
191 .I Ndbgetvalue
192 searches the database for an entry containing not only an
193 attribute/value pair,
194 .IR attr = val ,
195 but also a pair with the attribute
196 .IR rattr .
197 If successful, it returns a malloced copy of the null terminated value associated with
198 .IR rattr .
199 If
200 .I tp
201 is non nil,
202 .I *tp
203 will point to the entry. Otherwise the entry will be freeed.
204 .\" .PP
205 .\" .I Csgetvalue
206 .\" is like
207 .\" .I ndbgetvalue
208 .\" but queries the connection server
209 .\" instead of looking directly at the database.
210 .\" Its first argument specifies the network root to use.
211 .\" If the argument is 0, it defaults to
212 .\" \f5"/net"\f1.
213 .PP
214 .I Ndbfree
215 frees a list of tuples returned by one of the other
216 routines.
217 .PP
218 .I Ipattr
219 takes the name of an IP system and returns the attribute
220 it corresponds to:
221 .RS
222 .TP
223 .B dom
224 domain name
225 .TP
226 .B ip
227 Internet number
228 .TP
229 .B sys
230 system name
231 .RE
232 .PP
233 .I Ndbgetipaddr
234 looks in
235 .I db
236 for an entry matching
237 .I sys
238 as the value of a
239 .B sys=
240 or
241 .B dom=
242 attribute/value pair and returns all IP addresses in the entry.
243 If
244 .I sys
245 is already an IP address, a tuple containing just
246 that address is returned.
247 .PP
248 .I Ndbipinfo
249 looks up Internet protocol information about a system.
250 This is an IP aware search. It looks first for information
251 in the system's database entry and then in the database entries
252 for any IP subnets or networks containing the system.
253 The system is identified by the
254 attribute/value pair,
255 .IR attr = val .
256 .I Ndbipinfo
257 returns a list of tuples whose attributes match the
258 attributes in the
259 .I n
260 element array
261 .IR attrs .
262 For example, consider the following database entries describing a network,
263 a subnetwork, and a system.
264 .PP
265 .EX
266 ipnet=big ip=10.0.0.0
267 dns=dns.big.com
268 smtp=smtp.big.com
269 ipnet=dept ip=10.1.1.0 ipmask=255.255.255.0
270 smtp=smtp1.big.com
271 ip=10.1.1.4 dom=x.big.com
272 bootf=/386/9pc
273 .EE
274 .PP
275 Calling
276 .PP
277 .EX
278 ndbipinfo(db, "dom", "x.big.com", ["bootf" "smtp" "dns"], 3)
279 .EE
280 .PP
281 will return the tuples
282 .BR bootf=/386/9pc ,
283 .BR smtp=smtp1.big.com ,
284 and
285 .BR dns=dns.big.com .
286 .\" .PP
287 .\" .I Csipinfo
288 .\" is to
289 .\" .I ndbipinfo
290 .\" as
291 .\" .I csgetval
292 .\" is to
293 .\" .IR ndbgetval .
294 .PP
295 The next three routines are used by programs that create the
296 hash tables and database files.
297 .I Ndbhash
298 computes a hash offset into a table of length
299 .I hlen
300 for the string
301 .IR val .
302 .I Ndbparse
303 reads and parses the next entry from the database file.
304 Multiple calls to
305 .IR ndbparse
306 parse sequential entries in the database file.
307 A zero is returned at end of file.
308 .\" .PP
309 .\" .I Dnsquery
310 .\" submits a query about
311 .\" .I domainname
312 .\" to the
313 .\" .I ndb/dns
314 .\" mounted at
315 .\" .IB netroot /dns.
316 .\" It returns a linked list of
317 .\" .I Ndbtuple's
318 .\" representing a single database entry.
319 .\" The tuples are logicly arranged into lines using the
320 .\" .B line
321 .\" fieldin the structure.
322 .\" The possible
323 .\" .IR type 's
324 .\" of query are and the attributes on each returned tuple line is:
325 .\" .TP
326 .\" .B ip
327 .\" find the IP addresses. Returns
328 .\" domain name
329 .\" .RI ( dom )
330 .\" and ip address
331 .\" .RI ( ip )
332 .\" .TP
333 .\" .B mx
334 .\" look up the mail exchangers. Returns preference
335 .\" .RI ( pref )
336 .\" and exchanger
337 .\" .RI ( mx )
338 .\" .TP
339 .\" .B ptr
340 .\" do a reverse query. Here
341 .\" .I domainname
342 .\" must be an
343 .\" .SM ASCII
344 .\" IP address. Returns reverse name
345 .\" .RI ( ptr )
346 .\" and domain name
347 .\" .RI ( dom )
348 .\" .TP
349 .\" .B cname
350 .\" get the system that this name is a nickname for. Returns the nickname
351 .\" .RI ( dom )
352 .\" and the real name
353 .\" .RI ( cname )
354 .\" .TP
355 .\" .B soa
356 .\" return the start of area record for this field. Returns
357 .\" area name
358 .\" .RI ( dom ),
359 .\" primary name server
360 .\" .RI ( ns ),
361 .\" serial number
362 .\" .RI ( serial ),
363 .\" refresh time in seconds
364 .\" .RI ( refresh ),
365 .\" retry time in seconds
366 .\" .RI ( retry ),
367 .\" expiration time in seconds
368 .\" .RI ( expire ),
369 .\" and minimum time to lie
370 .\" .RI ( ttl ).
371 .\" .TP
372 .\" .B ns
373 .\" name servers. Returns domain name
374 .\" .RI ( dom )
375 .\" and name server
376 .\" .RI ( ns )
377 .PP
378 .I Ndbfindattr
379 searches
380 .I entry
381 for the tuple
382 with attribute
383 .I attr
384 and returns a pointer to the tuple.
385 If
386 .I line
387 points to a particular line in the entry, the
388 search starts there and then wraps around to the beginning
389 of the entry.
390 .PP
391 All of the routines provided to search the database
392 provide an always consistent view of the relevant
393 files. However, it may be advantageous for an application
394 to read in the whole database using
395 .I ndbopen
396 and
397 .I ndbparse
398 and provide its own search routines. The
399 .I ndbchanged
400 routine can be used by the application to periodicly
401 check for changes. It returns zero
402 if none of the files comprising the database have
403 changes and non-zero if they have.
404 .PP
405 Finally, a number of routines are provided for manipulating
406 tuples.
407 .PP
408 .I Ndbdiscard
409 removes attr/val pair
410 .I a
411 from tuple
412 .I t
413 and frees it.
414 If
415 .I a
416 isn't in
417 .I t
418 it is just freed.
419 .PP
420 .I Ndbconcatenate
421 concatenates two tuples and returns the result. Either
422 or both tuples may be nil.
423 .PP
424 .I Ndbreorder
425 reorders a tuple
426 .IR t
427 to make the line containing attr/val pair
428 .I a
429 first in the entry and making
430 .I a
431 first in its line.
432 .PP
433 .I Ndbsubstitute
434 replaces a single att/val pair
435 .I from
436 in
437 .I t
438 with the tuple
439 .IR to .
440 All attr/val pairs in
441 .I to
442 end up on the same line.
443 .I from
444 is freed.
445 .SH FILES
446 .TP
447 .B \*9/ndb
448 directory of network database files
449 .PD
450 .SH SOURCE
451 .B \*9/src/libndb
452 .SH SEE ALSO
453 .MR ndb (1)
454 .MR ndb (7)
455 .SH DIAGNOSTICS
456 .IR Ndbgetvalue
457 and
458 .I ndblookvalue
459 set
460 .I errstr
461 to
462 .B "buffer too short"
463 if the buffer provided isn't long enough for the
464 returned value.
465 .SH BUGS
466 .IR Ndbgetval
467 and
468 .I ndblookval
469 are deprecated versions of
470 .IR ndbgetvalue
471 and
472 .IR ndblookvalue .
473 They expect a fixed 64 byte long result
474 buffer and existed when the values of a
475 .I Ndbtuple
476 structure where fixed length.