Commit | Line | Data |
---|---|---|
53e9b2ee KM |
1 | .\" Copyright (c) 1985 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
5 | .\" @(#)ndbm.3 6.1 (Berkeley) %G% | |
6 | .\" | |
7 | .TH NDBM 3X "" | |
8 | .UC 6 | |
9 | .SH NAME | |
10 | dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- data base subroutines | |
11 | .SH SYNOPSIS | |
12 | .nf | |
13 | .PP | |
14 | .ft B | |
15 | #include <ndbm.h> | |
16 | .PP | |
17 | .ft B | |
18 | typedef struct { | |
19 | char *dptr; | |
20 | int dsize; | |
21 | } datum; | |
22 | .PP | |
23 | .ft B | |
24 | DBM *dbm_open(file, flags, mode) | |
25 | char *file; | |
26 | int flags, mode; | |
27 | .PP | |
28 | .ft B | |
29 | dbm_close(db) | |
30 | DBM *db; | |
31 | .PP | |
32 | .ft B | |
33 | datum dbm_fetch(db, key) | |
34 | DBM *db; | |
35 | struct key; | |
36 | datum key; | |
37 | .PP | |
38 | .ft B | |
39 | dbm_store(db, key, content, flags) | |
40 | DBM *db; | |
41 | datum key, content; | |
42 | int flags; | |
43 | .PP | |
44 | .ft B | |
45 | dbm_delete(db, key) | |
46 | DBM *db; | |
47 | datum key; | |
48 | .PP | |
49 | .ft B | |
50 | datum dbm_firstkey(db) | |
51 | DBM *db; | |
52 | .PP | |
53 | .ft B | |
54 | datum dbm_nextkey(db) | |
55 | DBM *db; | |
56 | .PP | |
57 | .ft B | |
58 | datum dbm_error(db) | |
59 | DBM *db; | |
60 | .PP | |
61 | .ft B | |
62 | datum dbm_clearerr(db) | |
63 | DBM *db; | |
64 | .SH DESCRIPTION | |
65 | These functions maintain key/content pairs in a data base. | |
66 | The functions will handle very large (a billion blocks) | |
67 | databases and will access a keyed item in one or two file system accesses. | |
68 | .PP | |
69 | .IR Key s | |
70 | and | |
71 | .IR content s | |
72 | are described by the | |
73 | .I datum | |
74 | typedef. A | |
75 | .I datum | |
76 | specifies a string of | |
77 | .I dsize | |
78 | bytes pointed to by | |
79 | .I dptr. | |
80 | Arbitrary binary data, as well as normal ASCII strings, are allowed. | |
81 | The data base is stored in two files. | |
82 | One file is a directory containing a bit map and has `.dir' as its suffix. | |
83 | The second file contains all data and has `.pag' as its suffix. | |
84 | .PP | |
85 | Before a database can be accessed, it must be opened by | |
86 | .IR dbm_open . | |
87 | This will open and/or create the files | |
88 | .IB file .dir | |
89 | and | |
90 | .IB file .pag | |
91 | depending on the flags parameter (see | |
92 | .IR open (2)). | |
93 | .PP | |
94 | Once open, the data stored under a key is accessed by | |
95 | .I dbm_fetch | |
96 | and data is placed under a key by | |
97 | .IR dbm_store . | |
98 | The | |
99 | .I flags | |
100 | field can be either | |
101 | .B DBM_INSERT | |
102 | or | |
103 | .B DBM_REPLACE. | |
104 | .B DBM_INSERT | |
105 | will only insert new entries into the database and will not | |
106 | change an existing entry with the same key. | |
107 | .B DBM_REPLACE | |
108 | will replace an existing entry if it has the same key. | |
109 | A key (and its associated contents) is deleted by | |
110 | .IR dbm_delete . | |
111 | A linear pass through all keys in a database may be made, | |
112 | in an (apparently) random order, by use of | |
113 | .I dbm_firstkey | |
114 | and | |
115 | .IR dbm_nextkey . | |
116 | .I Dbm_firstkey | |
117 | will return the first key in the database. | |
118 | .I Dbm_nextkey | |
119 | will return the next key in the database. | |
120 | This code will traverse the data base: | |
121 | .IP | |
122 | .B for | |
123 | (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db)) | |
124 | .PP | |
125 | .I Dbm_error | |
126 | returns non-zero when an error has occured reading or writing the database. | |
127 | .I Dbm_clearerr | |
128 | Resets the error condition on the named database. | |
129 | .SH DIAGNOSTICS | |
130 | All functions that return an | |
131 | .I int | |
132 | indicate errors with negative values. A zero return indicates ok. | |
133 | Routines that return a | |
134 | .I datum | |
135 | indicate errors with a null (0) | |
136 | .I dptr. | |
137 | .SH BUGS | |
138 | The `.pag' file will contain holes so that its apparent size is about | |
139 | four times its actual content. Older UNIX systems may create real | |
140 | file blocks for these holes when touched. These files cannot be copied | |
141 | by normal means (cp, cat, tp, tar, ar) without filling in the holes. | |
142 | .PP | |
143 | .I Dptr | |
144 | pointers returned by these subroutines point into static storage | |
145 | that is changed by subsequent calls. | |
146 | .PP | |
147 | The sum of the sizes of a key/content pair must not exceed | |
148 | the internal block size (currently 4096 bytes). | |
149 | Moreover all key/content pairs that hash together must fit on a single block. | |
150 | .I Dbm_store | |
151 | will return an error in the event that a disk block fills with inseparable data. | |
152 | .PP | |
153 | .I Dbm_delete | |
154 | does not physically reclaim file space, | |
155 | although it does make it available for reuse. | |
156 | .PP | |
157 | The order of keys presented by | |
158 | .I dbm_firstkey | |
159 | and | |
160 | .I dbm_nextkey | |
161 | depends on a hashing function, not on anything interesting. |