Commit | Line | Data |
---|---|---|
3846ebac TL |
1 | .TH DBM 3X |
2 | .SH NAME | |
3 | dbminit, fetch, store, delete, firstkey, nextkey \- data base subroutines | |
4 | .SH SYNOPSIS | |
5 | .nf | |
6 | .PP | |
7 | .B "typedef struct { char *dptr; int dsize; } datum;" | |
8 | .PP | |
9 | .B dbminit(file) | |
10 | .B char *file; | |
11 | .PP | |
12 | .B datum fetch(key) | |
13 | .B datum key; | |
14 | .PP | |
15 | .B store(key, content) | |
16 | .B datum key, content; | |
17 | .PP | |
18 | .B delete(key) | |
19 | .B datum key; | |
20 | .PP | |
21 | .B datum firstkey(); | |
22 | .PP | |
23 | .B datum nextkey(key); | |
24 | .B datum key; | |
25 | .SH DESCRIPTION | |
26 | These functions maintain | |
27 | key/content pairs in a data base. | |
28 | The functions will handle very large | |
29 | (a billion blocks) | |
30 | databases and will access a keyed item | |
31 | in one or two filesystem accesses. | |
32 | The functions are obtained with the loader option | |
33 | .BR \-ldbm . | |
34 | .PP | |
35 | .IR Key s | |
36 | and | |
37 | .IR content s | |
38 | are | |
39 | described by the | |
40 | .I datum | |
41 | typedef. | |
42 | A | |
43 | .I datum | |
44 | specifies a string of | |
45 | .I dsize | |
46 | bytes pointed to by | |
47 | .I dptr. | |
48 | Arbitrary binary data, as well as normal | |
49 | ASCII strings, are allowed. | |
50 | The data base is stored in two files. | |
51 | One file is a directory containing a bit map | |
52 | and has `.dir' as its suffix. | |
53 | The second file contains all data and | |
54 | has `.pag' as its suffix. | |
55 | .PP | |
56 | Before a database can be accessed, | |
57 | it must be opened by | |
58 | .I dbminit. | |
59 | At the time of this call, | |
60 | the files | |
61 | .IB file .dir | |
62 | and | |
63 | .IB file .pag | |
64 | must exist. | |
65 | (An empty database is created by | |
66 | creating zero-length | |
67 | `.dir' and `.pag' files.) | |
68 | .PP | |
69 | Once open, | |
70 | the data stored under a key is | |
71 | accessed by | |
72 | .I fetch | |
73 | and data is placed under a key | |
74 | by | |
75 | .IR store . | |
76 | A key (and its associated contents) | |
77 | is deleted by | |
78 | .IR delete . | |
79 | A linear pass through all keys in a database | |
80 | may be made, | |
81 | in an (apparently) random order, | |
82 | by use of | |
83 | .I firstkey | |
84 | and | |
85 | .IR nextkey . | |
86 | .I Firstkey | |
87 | will return the first key | |
88 | in the database. | |
89 | With any key | |
90 | .I nextkey | |
91 | will return the next key in the database. | |
92 | This code will traverse the data base: | |
93 | .PP | |
94 | for(key=firstkey(); key.dptr!=NULL; key=nextkey(key)) | |
95 | .SH DIAGNOSTICS | |
96 | All functions that return an | |
97 | .I int | |
98 | indicate errors with negative values. | |
99 | A zero return indicates ok. | |
100 | Routines that return a | |
101 | .I datum | |
102 | indicate errors with a null (0) | |
103 | .I dptr. | |
104 | .SH BUGS | |
105 | The | |
106 | `.pag' | |
107 | file will contain holes so | |
108 | that its apparent size is about | |
109 | four times its actual content. | |
110 | Older UNIX systems may create real | |
111 | file blocks for these holes when touched. | |
112 | These files cannot be copied | |
113 | by normal means (cp, cat, tp, tar, ar) | |
114 | without filling in the holes. | |
115 | .PP | |
116 | .I Dptr | |
117 | pointers returned | |
118 | by these subroutines | |
119 | point into static storage | |
120 | that is changed by subsequent calls. | |
121 | .PP | |
122 | The sum of the sizes of | |
123 | a | |
124 | key/content pair must not exceed | |
125 | the internal block size | |
126 | (currently 512 bytes). | |
127 | Moreover all key/content pairs that hash | |
128 | together must fit on a single block. | |
129 | .I Store | |
130 | will return an error in the event that | |
131 | a disk block fills with inseparable data. | |
132 | .PP | |
133 | .I Delete | |
134 | does not physically reclaim file space, | |
135 | although it does make it available for reuse. | |
136 | .PP | |
137 | The order of keys presented by | |
138 | .I firstkey | |
139 | and | |
140 | .I nextkey | |
141 | depends on a hashing function, not on anything | |
142 | interesting. |