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 mx
 346 look up the mail exchangers.  Returns preference
 347 .RI ( pref )
 348 and exchanger
 349 .RI ( mx )
 350 .TP
 351 .B ptr
 352 do a reverse query.  Here
 353 .I domainname
 354 must be an
 355 .SM ASCII
 356 IP address.  Returns reverse name
 357 .RI ( ptr )
 358 and domain name
 359 .RI ( dom )
 360 .TP
 361 .B cname
 362 get the system that this name is a nickname for.  Returns the nickname
 363 .RI ( dom )
 364 and the real name
 365 .RI ( cname )
 366 .TP
 367 .B soa
 368 return the start of area record for this field.  Returns
 369 area name
 370 .RI ( dom ),
 371 primary name server
 372 .RI ( ns ),
 373 serial number
 374 .RI ( serial ),
 375 refresh time in seconds
 376 .RI ( refresh ),
 377 retry time in seconds
 378 .RI ( retry ),
 379 expiration time in seconds
 380 .RI ( expire ),
 381 and minimum time to lie
 382 .RI ( ttl ).
 383 .TP
 384 .B ns
 385 name servers.  Returns domain name
 386 .RI ( dom )
 387 and name server
 388 .RI ( ns )
 389 .PP
 390 .I Ndbfindattr
 391 searches
 392 .I entry
 393 for the tuple
 394 with attribute
 395 .I attr
 396 and returns a pointer to the tuple.
 397 If
 398 .I line
 399 points to a particular line in the entry, the
 400 search starts there and then wraps around to the beginning
 401 of the entry.
 402 .PP
 403 All of the routines provided to search the database
 404 provide an always consistent view of the relevant
 405 files.  However, it may be advantageous for an application
 406 to read in the whole database using
 407 .I ndbopen
 408 and
 409 .I ndbparse
 410 and provide its own search routines.  The
 411 .I ndbchanged
 412 routine can be used by the application to periodically
 413 check for changes.  It returns zero
 414 if none of the files comprising the database have
 415 changes and non-zero if they have.
 416 .PP
 417 Finally, a number of routines are provided for manipulating tuples.
 418 .PP
 419 .I Ndbdiscard
 420 removes attr/val pair
 421 .I a
 422 from tuple
 423 .I t
 424 and frees it.
 425 If
 426 .I a
 427 isn't in
 428 .I t
 429 it is just freed.
 430 .PP
 431 .I Ndbconcatenate
 432 concatenates two tuples and returns the result.  Either
 433 or both tuples may be nil.
 434 .PP
 435 .I Ndbreorder
 436 reorders a tuple
 437 .IR t
 438 to make the line containing attr/val pair
 439 .I a
 440 first in the entry and making
 441 .I a
 442 first in its line.
 443 .PP
 444 .I Ndbsubstitute
 445 replaces a single att/val pair
 446 .I from
 447 in
 448 .I t
 449 with the tuple
 450 .IR to .
 451 All attr/val pairs in
 452 .I to
 453 end up on the same line.
 454 .I from
 455 is freed.
 456 .PP
 457 .I Ndbsetmalloctag
 458 sets the malloc tag
 459 (see
 460 .I setmalloctag
 461 in
 462 .IR malloc (2))
 463 of each tuple in the list
 464 .I t
 465 to
 466 .IR tag .
 467 .SH FILES
 468 .BR /lib/ndb "    directory of network database files
 469 .SH SOURCE
 470 .B /sys/src/libndb
 471 .SH SEE ALSO
 472 .IR ndb (6),
 473 .IR ndb (8)
 474 .SH DIAGNOSTICS
 475 .IR Ndbgetvalue ,
 476 .IR csgetvalue ,
 477 and
 478 .I ndblookvalue
 479 set
 480 .I errstr
 481 to
 482 .L "buffer too short"
 483 if the buffer provided isn't long enough for the
 484 returned value.
 485 .SH BUGS
 486 .IR Ndbgetval ,
 487 .IR csgetval ,
 488 and
 489 .I ndblookval
 490 are deprecated versions of
 491 .IR ndbgetvalue ,
 492 .IR csgetvalue ,
 493 and
 494 .IR ndblookvalue .
 495 They expect a fixed 64 byte long result
 496 buffer and existed when the values of a
 497 .I Ndbtuple
 498 structure were fixed length.