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