1ndbm(3C)                 Standard C Library Functions                 ndbm(3C)
2
3
4

NAME

6       ndbm,   dbm_clearerr,   dbm_close,  dbm_delete,  dbm_error,  dbm_fetch,
7       dbm_firstkey, dbm_nextkey, dbm_open, dbm_store - database functions
8

SYNOPSIS

10       #include <ndbm.h>
11
12       int dbm_clearerr(DBM *db);
13
14
15       void dbm_close(DBM *db);
16
17
18       int dbm_delete(DBM *db, datum key);
19
20
21       int dbm_error(DBM *db);
22
23
24       datum dbm_fetch(DBM *db, datum key);
25
26
27       datum dbm_firstkey(DBM *db);
28
29
30       datum dbm_nextkey(DBM *db);
31
32
33       DBM *dbm_open(const char *file, int open_flags, mode_t file_mode);
34
35
36       int dbm_store(DBM *db, datum key, datum content, int store_mode);
37
38

DESCRIPTION

40       These functions create, access and modify  a  database.  They  maintain
41       key/content  pairs in a database. The functions will handle large data‐
42       bases (up to a billion blocks) and will access a keyed item in  one  or
43       two  file  system accesses. This package replaces the earlier dbm(3UCB)
44       library, which managed only a single database.
45
46
47       keys and contents are described by the datum typedef. A datum  consists
48       of  at  least two members, dptr and dsize. The dptr member points to an
49       object that is dsize bytes in length.  Arbitrary binary data,  as  well
50       as  ASCII  character strings, may be stored in the object pointed to by
51       dptr.
52
53
54       The database is stored in two files. One file is a directory containing
55       a bit map of keys and has .dir as its suffix.  The second file contains
56       all data and has .pag as its suffix.
57
58
59       The dbm_open() function opens a database.  The  file  argument  to  the
60       function is the pathname of the database.  The function opens two files
61       named file.dir and file.pag. The open_flags argument has the same mean‐
62       ing  as the flags argument of open(2) except that a database opened for
63       write-only access opens the files  for  read  and  write  access.   The
64       file_mode  argument  has  the  same  meaning  as  the third argument of
65       open(2).
66
67
68       The dbm_close() function closes a database.  The argument db must be  a
69       pointer  to  a  dbm  structure  that  has  been returned from a call to
70       dbm_open().
71
72
73       The dbm_fetch() function reads a record from a database.  The  argument
74       db  is  a pointer to a database structure that has been returned from a
75       call to dbm_open(). The argument key is a datum that has been  initial‐
76       ized  by  the  application program to the value of the key that matches
77       the key of the record the program is fetching.
78
79
80       The dbm_store() function writes a record to a database.   The  argument
81       db  is  a pointer to a database structure that has been returned from a
82       call to dbm_open(). The argument key is a datum that has been  initial‐
83       ized by the application program to the value of the key that identifies
84       (for subsequent reading, writing or deleting) the record the program is
85       writing.  The  argument content is a datum that has been initialized by
86       the application program to the value of the record the program is writ‐
87       ing.  The argument store_mode controls whether dbm_store() replaces any
88       pre-existing record that has the same key that is specified by the  key
89       argument.   The  application  program  must  set  store_mode  to either
90       DBM_INSERT or DBM_REPLACE.  If the  database  contains  a  record  that
91       matches  the  key  argument and store_mode is DBM_REPLACE, the existing
92       record is replaced with the new record.  If  the  database  contains  a
93       record  that matches the key argument and store_mode is DBM_INSERT, the
94       existing record is not replaced with the new record.  If  the  database
95       does  not contain a record that matches the key argument and store_mode
96       is either DBM_INSERT or DBM_REPLACE, the new record is inserted in  the
97       database.
98
99
100       The  dbm_delete()  function deletes a record and its key from the data‐
101       base.  The argument db is a pointer to a database  structure  that  has
102       been  returned  from  a call to dbm_open(). The argument key is a datum
103       that has been initialized by the application program to  the  value  of
104       the key that identifies the record the program is deleting.
105
106
107       The dbm_firstkey() function returns the first key in the database.  The
108       argument db is a pointer to a database structure that has been returned
109       from a call to dbm_open().
110
111
112       The  dbm_nextkey()  function returns the next key in the database.  The
113       argument db is a pointer to a database structure that has been returned
114       from  a  call to dbm_open(). The dbm_firstkey() function must be called
115       before calling dbm_nextkey(). Subsequent calls to dbm_nextkey()  return
116       the next key until all of the keys in the database have been returned.
117
118
119       The  dbm_error()  function returns the error condition of the database.
120       The argument db is a pointer to a  database  structure  that  has  been
121       returned from a call to dbm_open().
122
123
124       The dbm_clearerr() function clears the error condition of the database.
125       The argument db is a pointer to a  database  structure  that  has  been
126       returned from a call to dbm_open().
127
128
129       These  database  functions  support  key/content pairs of at least 1024
130       bytes.
131

RETURN VALUES

133       The dbm_store() and dbm_delete() functions return 0 when  they  succeed
134       and a negative value when they fail.
135
136
137       The  dbm_store()  function returns 1 if it is called with a flags value
138       of DBM_INSERT and the function finds an existing record with  the  same
139       key.
140
141
142       The  dbm_error()  function  returns 0 if the error condition is not set
143       and returns a non-zero value if the error condition is set.
144
145
146       The return value of dbm_clearerr() is unspecified .
147
148
149       The dbm_firstkey() and dbm_nextkey() functions return a key datum. When
150       the  end  of  the  database is reached, the dptr member of the key is a
151       null pointer.  If an error is detected, the dptr member of the key is a
152       null pointer and the error condition of the database is set.
153
154
155       The  dbm_fetch()  function returns a content datum. If no record in the
156       database matches the key or if an error condition has been detected  in
157       the database, the dptr member of the content is a null pointer.
158
159
160       The  dbm_open() function returns a pointer to a database structure.  If
161       an error is detected during the operation, dbm_open()  returns  a  (DBM
162       *)0.
163

ERRORS

165       No errors are defined.
166

USAGE

168       The following code can be used to traverse the database:
169
170         for(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))
171
172
173
174       The  dbm_  functions provided in this library should not be confused in
175       any way with those of a  general-purpose  database  management  system.
176       These functions do not provide for multiple search keys per entry, they
177       do not protect against multi-user access (in other words  they  do  not
178       lock  records  or files), and they do not provide the many other useful
179       database functions that are found in more  robust  database  management
180       systems.   Creating and updating databases by use of these functions is
181       relatively slow because of data copies that occur upon hash collisions.
182       These  functions  are  useful for applications requiring fast lookup of
183       relatively static information that is to be indexed by a single key.
184
185
186       The dptr pointers returned by these functions  may  point  into  static
187       storage that may be changed by subsequent calls.
188
189
190       The  dbm_delete()  function  does  not  physically  reclaim file space,
191       although it does make it available for reuse.
192
193
194       After calling dbm_store() or dbm_delete() during  a  pass  through  the
195       keys  by dbm_firstkey() and dbm_nextkey(), the application should reset
196       the database by calling dbm_firstkey() before  again  calling  dbm_nex‐
197       tkey().
198

EXAMPLES

200       Example 1 Using the Database Functions
201
202
203       The  following  example  stores and retrieves a phone number, using the
204       name as the key.  Note that this example does not include error  check‐
205       ing.
206
207
208         #include <ndbm.h>
209         #include <stdio.h>
210         #include <fcntl.h>
211         #define NAME      "Bill"
212         #define PHONE_NO          "123-4567"
213         #define DB_NAME   "phones"
214         main()
215         {
216              DBM *db;
217              datum name = {NAME, sizeof (NAME)};
218              datum put_phone_no = {PHONE_NO, sizeof (PHONE_NO)};
219              datum get_phone_no;
220              /* Open the database and store the record */
221              db = dbm_open(DB_NAME, O_RDWR | O_CREAT, 0660);
222              (void) dbm_store(db, name, put_phone_no, DBM_INSERT);
223              /* Retrieve the record */
224              get_phone_no = dbm_fetch(db, name);
225              (void) printf("Name: %s, Phone Number: %s\n", name.dptr,
226              get_phone_no.dptr);
227              /* Close the database */
228              dbm_close(db);
229              return (0);
230         }
231
232

ATTRIBUTES

234       See attributes(5) for descriptions of the following attributes:
235
236
237
238
239       ┌─────────────────────────────┬─────────────────────────────┐
240       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
241       ├─────────────────────────────┼─────────────────────────────┤
242       │Interface Stability          │Standard                     │
243       ├─────────────────────────────┼─────────────────────────────┤
244       │MT-Level                     │Unsafe                       │
245       └─────────────────────────────┴─────────────────────────────┘
246

SEE ALSO

248       ar(1),   cat(1),   cp(1),  tar(1),  open(2),  dbm(3UCB),  netconfig(4),
249       attributes(5), standards(5)
250

NOTES

252       The .pag file will contain holes so  that  its  apparent  size  may  be
253       larger  than  its  actual content. Older versions of the UNIX operating
254       system may create real file blocks for these holes when touched.  These
255       files  cannot be copied by normal means ( cp(1), cat(1), tar(1), ar(1))
256       without filling in the holes.
257
258
259       The sum of the sizes of a key/content pair must not exceed the internal
260       block  size (currently 1024 bytes). Moreover all key/content pairs that
261       hash together must fit on a single block. dbm_store()  will  return  an
262       error in the event that a disk block fills with inseparable data.
263
264
265       The order of keys presented by dbm_firstkey() and dbm_nextkey() depends
266       on a hashing function.
267
268
269       There are no interlocks and no reliable cache flushing; thus concurrent
270       updating and reading is risky.
271
272
273       The database files (file.dir and file.pag) are binary and are architec‐
274       ture-specific (for example, they  depend  on  the  architecture's  byte
275       order.)  These files are not guaranteed to be portable across architec‐
276       tures.
277
278
279
280SunOS 5.11                        17 Sep 2001                         ndbm(3C)
Impressum