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