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