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
|
.\" David Leonard, 1998. Placed in the public domain.
.\" $OpenBSD: ndbm.3,v 1.2 1998/05/13 17:15:32 deraadt Exp $
.Dd May 13, 1998
.Os OpenBSD
.Dt NDBM 3
.Sh NAME
.Nm ndbm
.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" "int mode"
.Ft int
.Fn dbm_pagfno "DBM *db"
.Ft int
.Fn dbm_store "DBM *db" "datum key" "datum content" "int store_mode"
.Sh DESCRIPTION
These functions provide a dbm- and 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.
Both the key and the content are passed about in the following
.Ft datum
data structure:
.Bd -literal -offset indent
typedef struct {
char *dptr;
int 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_READONLY .
.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
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 datbase 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 with the
.Va dptr
field set to
.Dv NULL .
.Pp
The
.Fn dbm_open
function returns
.Dv NULL
on error, and sets
.Va errno
appropriately.
.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 db 3 ,
.Xr hash 3 ,
.Xr open 2 .
|
