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