sys/man/2/ndb

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