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