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