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