1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
.\" David Leonard, 1998. Placed in the public domain.
.\" $OpenBSD: ndbm.3,v 1.16 2007/05/31 19:19:28 jmc Exp $
.Dd $Mdocdate: May 31 2007 $
.Dt NDBM 3
.Os
.Sh NAME
.Nm dbm_clearerr ,
.Nm dbm_close ,
.Nm dbm_delete ,
.Nm dbm_dirfno ,
.Nm dbm_error ,
.Nm dbm_fetch ,
.Nm dbm_firstkey ,
.Nm dbm_nextkey ,
.Nm dbm_open ,
.Nm dbm_pagfno ,
.Nm dbm_rdonly ,
.Nm dbm_store
.Nd database access methods
.Sh SYNOPSIS
.Fd #include <ndbm.h>
.Ft int
.Fn dbm_clearerr "DBM *db"
.Ft void
.Fn dbm_close "DBM *db"
.Ft int
.Fn dbm_delete "DBM *db" "datum key"
.Ft int
.Fn dbm_dirfno "DBM *db"
.Ft int
.Fn dbm_error "DBM *db"
.Ft datum
.Fn dbm_fetch "DBM *db" "datum key"
.Ft datum
.Fn dbm_firstkey "DBM *db"
.Ft datum
.Fn dbm_nextkey "DBM *db"
.Ft "DBM *"
.Fn dbm_open "const char *file" "int flags" "mode_t mode"
.Ft int
.Fn dbm_pagfno "DBM *db"
.Ft int
.Fn dbm_rdonly "DBM *db"
.Ft int
.Fn dbm_store "DBM *db" "datum key" "datum content" "int store_mode"
.Sh DESCRIPTION
These functions provide a ndbm-compatible interface to the
database access methods described in
.Xr db 3 .
Each unique record in the database is a key/content pair,
the components of which may be any arbitrary binary data.
The key and the content data are described by the
.Ft datum
data structure:
.Bd -literal -offset indent
typedef struct {
void *dptr;
size_t dsize;
} datum;
.Ed
.Pp
The
.Fn dbm_open
function is used to open a database in the file named by
.Fa file ,
suffixed with
.Dv DBM_SUFFIX
.Pq Sq Pa .db .
If necessary, the file is created with mode
.Ar mode .
Access to this file depends on the
.Fa flags
parameter (see
.Xr open 2 ) .
Read-only access may be indicated by specifying
.Dv DBM_RDONLY .
The
.Fn dbm_rdonly
function may be used to determine if a database is opened for read-only
access.
.Pp
Once the database is open,
.Fn dbm_fetch
is used to retrieve the data content associated with the key
.Fa key .
Similarly,
.Fn dbm_store
is used to store the
.Fa content
data with the key
.Fa key .
When storing, the
.Fa store_mode
parameter must be one of:
.Bl -tag -width DBM_REPLACE -offset indent
.It Dv DBM_INSERT
Only insert new keys into the database.
Existing key/content pairs are untouched.
.It Dv DBM_REPLACE
Replace any existing entry with the same key.
Any previously stored records with the same key are lost.
.El
.Pp
The
.Fn dbm_delete
function removes the key
.Fa key
and its associated content from the database.
.Pp
The functions
.Fn dbm_firstkey
and
.Fn dbm_nextkey
are used to iterate over all of the records in the database.
Each record will be reached exactly once, but in no particular order.
The
.Fn dbm_firstkey
function returns the first record of the database, and thereafter
.Fn dbm_nextkey
returns the following records.
The following code traverses the entire database:
.Bd -literal -offset indent
for (key = dbm_firstkey(db); key.dptr != NULL;
key = dbm_nextkey(db))
.Ed
.Pp
The behaviour of
.Fn dbm_nextkey
is undefined if the database is modified after a call to
.Fn dbm_firstkey .
.Pp
The
.Fn dbm_error
function returns the last error condition of the database,
or 0 if no error had occurred or had been cleared.
The
.Fn dbm_clearerr
function clears the error condition of the database.
.Pp
The
.Fn dbm_dirfno
function is used to find the file descriptor associated with the
directory file of an open database.
Since a directory bitmap file is not used in this implementation,
this function returns the file descriptor of the database file opened with
.Fn dbm_open .
.Pp
The
.Fn dbm_pagfno
function is used to find the file descriptor associated with the
page file of an open database.
Since a page file is not used in this implementation, this function
is implemented as a macro that always returns the (undefined) value
.Dv DBM_PAGFNO_NOT_AVAILABLE .
.Pp
The database is closed with the
.Fn dbm_close
function.
Thereafter, the
.Fa db
handle is invalid.
.Ss Implementation notes
The underlying database is a
.Xr hash 3
database with a
bucket size of 4096,
a filling factor of 40,
default hashing function and cache size,
and uses the host's native byte order.
.Sh RETURN VALUES
Upon successful completion, all functions that return
.Ft int
return a value of 0, otherwise a negative value is returned.
.Pp
Routines that return a
.Ft datum
indicate errors by setting the
.Va dptr
field to
.Dv NULL .
.Pp
The
.Fn dbm_open
function returns
.Dv NULL
on error, and sets
.Va errno
appropriately.
On success, it returns a handle to the database that should be
used as the
.Fa db
argument in the other functions.
.Pp
The
.Fn dbm_store
function returns 1 when it is called with a
.Fa flags
value of
.Dv DBM_INSERT
and a record with the specified key already exists.
.Sh ERRORS
If an error occurs, the error can be retrieved with
.Fn dbm_error
and corresponds to those errors described in
.Xr db 3 .
.Sh SEE ALSO
.Xr open 2 ,
.Xr db 3 ,
.Xr dbm 3 ,
.Xr hash 3
|
