ndb 9.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490
  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. 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. .PP
  88. .B
  89. void ndbsetmalloctag(Ndbtuple *t, uintptr tag)
  90. .SH DESCRIPTION
  91. These routines are used by network administrative programs to search
  92. the network database.
  93. They operate on the database files described in
  94. .IR ndb (6).
  95. .PP
  96. .I Ndbopen
  97. opens the database
  98. .I file
  99. and calls
  100. .IR malloc (2)
  101. to allocate a buffer for it.
  102. If
  103. .I file
  104. is zero, all network database files are opened.
  105. .PP
  106. .I Ndbcat
  107. concatenates two open databases. Either argument may be
  108. nil.
  109. .PP
  110. .I Ndbreopen
  111. checks if the database files associated with
  112. .I db
  113. have changed and if so throws out any cached information and reopens
  114. 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 freeed.
  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. For example, consider the following database entries describing a network,
  266. a subnetwork, and a system.
  267. .PP
  268. .EX
  269. ipnet=big ip=10.0.0.0
  270. dns=dns.big.com
  271. smtp=smtp.big.com
  272. ipnet=dept ip=10.1.1.0 ipmask=255.255.255.0
  273. smtp=smtp1.big.com
  274. ip=10.1.1.4 dom=x.big.com
  275. bootf=/386/9pc
  276. .EE
  277. .PP
  278. Calling
  279. .PP
  280. .EX
  281. ndbipinfo(db, "dom", "x.big.com", ["bootf" "smtp" "dns"], 3)
  282. .EE
  283. .PP
  284. will return the tuples
  285. .BR bootf=/386/9pc ,
  286. .BR smtp=smtp1.big.com ,
  287. and
  288. .BR dns=dns.big.com .
  289. .PP
  290. .I Csipinfo
  291. is to
  292. .I ndbipinfo
  293. as
  294. .I csgetval
  295. is to
  296. .IR ndbgetval .
  297. .PP
  298. The next three routines are used by programs that create the
  299. hash tables and database files.
  300. .I Ndbhash
  301. computes a hash offset into a table of length
  302. .I hlen
  303. for the string
  304. .IR val .
  305. .I Ndbparse
  306. reads and parses the next entry from the database file.
  307. Multiple calls to
  308. .IR ndbparse
  309. parse sequential entries in the database file.
  310. A zero is returned at end of file.
  311. .PP
  312. .I Dnsquery
  313. submits a query about
  314. .I domainname
  315. to the
  316. .I ndb/dns
  317. mounted at
  318. .IB netroot /dns.
  319. It returns a linked list of
  320. .I Ndbtuple's
  321. representing a single database entry.
  322. The tuples are logicly arranged into lines using the
  323. .B line
  324. fieldin the structure.
  325. The possible
  326. .IR type 's
  327. of query are and the attributes on each returned tuple line is:
  328. .TP
  329. .B ip
  330. find the IP addresses. Returns
  331. domain name
  332. .RI ( dom )
  333. and ip address
  334. .RI ( ip )
  335. .TP
  336. .B mx
  337. look up the mail exchangers. Returns preference
  338. .RI ( pref )
  339. and exchanger
  340. .RI ( mx )
  341. .TP
  342. .B ptr
  343. do a reverse query. Here
  344. .I domainname
  345. must be an
  346. .SM ASCII
  347. IP address. Returns reverse name
  348. .RI ( ptr )
  349. and domain name
  350. .RI ( dom )
  351. .TP
  352. .B cname
  353. get the system that this name is a nickname for. Returns the nickname
  354. .RI ( dom )
  355. and the real name
  356. .RI ( cname )
  357. .TP
  358. .B soa
  359. return the start of area record for this field. Returns
  360. area name
  361. .RI ( dom ),
  362. primary name server
  363. .RI ( ns ),
  364. serial number
  365. .RI ( serial ),
  366. refresh time in seconds
  367. .RI ( refresh ),
  368. retry time in seconds
  369. .RI ( retry ),
  370. expiration time in seconds
  371. .RI ( expire ),
  372. and minimum time to lie
  373. .RI ( ttl ).
  374. .TP
  375. .B ns
  376. name servers. Returns domain name
  377. .RI ( dom )
  378. and name server
  379. .RI ( ns )
  380. .PP
  381. .I Ndbfindattr
  382. searches
  383. .I entry
  384. for the tuple
  385. with attribute
  386. .I attr
  387. and returns a pointer to the tuple.
  388. If
  389. .I line
  390. points to a particular line in the entry, the
  391. search starts there and then wraps around to the beginning
  392. of the entry.
  393. .PP
  394. All of the routines provided to search the database
  395. provide an always consistent view of the relevant
  396. files. However, it may be advantageous for an application
  397. to read in the whole database using
  398. .I ndbopen
  399. and
  400. .I ndbparse
  401. and provide its own search routines. The
  402. .I ndbchanged
  403. routine can be used by the application to periodicly
  404. check for changes. It returns zero
  405. if none of the files comprising the database have
  406. changes and non-zero if they have.
  407. .PP
  408. Finally, a number of routines are provided for manipulating
  409. tuples.
  410. .PP
  411. .I Ndbdiscard
  412. removes attr/val pair
  413. .I a
  414. from tuple
  415. .I t
  416. and frees it.
  417. If
  418. .I a
  419. isn't in
  420. .I t
  421. it is just freed.
  422. .PP
  423. .I Ndbconcatenate
  424. concatenates two tuples and returns the result. Either
  425. or both tuples may be nil.
  426. .PP
  427. .I Ndbreorder
  428. reorders a tuple
  429. .IR t
  430. to make the line containing attr/val pair
  431. .I a
  432. first in the entry and making
  433. .I a
  434. first in its line.
  435. .PP
  436. .I Ndbsubstitute
  437. replaces a single att/val pair
  438. .I from
  439. in
  440. .I t
  441. with the tuple
  442. .IR to .
  443. All attr/val pairs in
  444. .I to
  445. end up on the same line.
  446. .I from
  447. is freed.
  448. .PP
  449. .I Ndbsetmalloctag
  450. sets the malloc tag
  451. (see
  452. .I setmalloctag
  453. in
  454. .IR malloc (2))
  455. of each tuple in the list
  456. .I t
  457. to
  458. .IR tag .
  459. .SH FILES
  460. .BR /lib/ndb " directory of network database files
  461. .SH SOURCE
  462. .B /sys/src/libndb
  463. .SH SEE ALSO
  464. .IR ndb (6)
  465. .IR ndb (8)
  466. .SH DIAGNOSTICS
  467. .IR Ndbgetvalue ,
  468. .IR csgetvalue ,
  469. and
  470. .I ndblookvalue
  471. set
  472. .I errstr
  473. to
  474. .L "buffer too short"
  475. if the buffer provided isn't long enough for the
  476. returned value.
  477. .SH BUGS
  478. .IR Ndbgetval ,
  479. .IR csgetval ,
  480. and
  481. .I ndblookval
  482. are deprecated versions of
  483. .IR ndbgetvalue ,
  484. .IR csgetvalue ,
  485. and
  486. .IR ndblookvalue .
  487. They expect a fixed 64 byte long result
  488. buffer and existed when the values of a
  489. .I Ndbtuple
  490. structure were fixed length.