1
0

ndb 9.5 KB

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