ndb.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.