1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
1 |
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved |
2
by Francesco Paolo Lovergine
* Alligned to linux main manpages edition. |
2 |
.TH "DBM_CLEARERR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" |
1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
3 |
.\" dbm_clearerr |
4 |
.SH NAME |
|
5 |
dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey, |
|
6 |
dbm_nextkey, dbm_open, dbm_store \- database
|
|
7 |
functions |
|
8 |
.SH SYNOPSIS |
|
9 |
.LP
|
|
10 |
\fB#include <ndbm.h>
|
|
11 |
.br
|
|
12 |
.sp
|
|
13 |
int dbm_clearerr(DBM *\fP\fIdb\fP\fB); |
|
14 |
.br
|
|
15 |
void dbm_close(DBM *\fP\fIdb\fP\fB); |
|
16 |
.br
|
|
17 |
int dbm_delete(DBM *\fP\fIdb\fP\fB, datum\fP \fIkey\fP\fB); |
|
18 |
.br
|
|
19 |
int dbm_error(DBM *\fP\fIdb\fP\fB); |
|
20 |
.br
|
|
21 |
datum dbm_fetch(DBM *\fP\fIdb\fP\fB, datum\fP \fIkey\fP\fB); |
|
22 |
.br
|
|
23 |
datum dbm_firstkey(DBM *\fP\fIdb\fP\fB); |
|
24 |
.br
|
|
25 |
datum dbm_nextkey(DBM *\fP\fIdb\fP\fB); |
|
26 |
.br
|
|
27 |
DBM *dbm_open(const char *\fP\fIfile\fP\fB, int\fP \fIopen_flags\fP\fB, |
|
28 |
mode_t\fP \fIfile_mode\fP\fB); |
|
29 |
.br
|
|
30 |
int dbm_store(DBM *\fP\fIdb\fP\fB, datum\fP \fIkey\fP\fB, datum\fP |
|
31 |
\fIcontent\fP\fB, int\fP |
|
32 |
\fIstore_mode\fP\fB); |
|
33 |
.br
|
|
34 |
\fP
|
|
35 |
.SH DESCRIPTION |
|
36 |
.LP
|
|
37 |
These functions create, access, and modify a database. |
|
38 |
.LP
|
|
39 |
A \fBdatum\fP consists of at least two members, \fIdptr\fP and \fIdsize\fP. |
|
40 |
The \fIdptr\fP member points to an object that |
|
41 |
is \fIdsize\fP bytes in length. Arbitrary binary data, as well as |
|
42 |
character strings, may be stored in the object pointed to by |
|
43 |
\fIdptr\fP. |
|
44 |
.LP
|
|
45 |
The database is stored in two files. One file is a directory containing |
|
46 |
a bitmap of keys and has \fB.dir\fP as its suffix. The |
|
47 |
second file contains all data and has \fB.pag\fP as its suffix. |
|
48 |
.LP
|
|
49 |
The \fIdbm_open\fP() function shall open a database. The \fIfile\fP |
|
50 |
argument to the function is the pathname of the database. |
|
51 |
The function opens two files named \fIfile\fP\fB.dir\fP and \fIfile\fP\fB.pag\fP. |
|
52 |
The \fIopen_flags\fP argument has the same |
|
53 |
meaning as the \fIflags\fP argument of \fIopen\fP() except that a |
|
54 |
database opened for |
|
55 |
write-only access opens the files for read and write access and the |
|
56 |
behavior of the O_APPEND flag is unspecified. The |
|
57 |
\fIfile_mode\fP argument has the same meaning as the third argument |
|
58 |
of \fIopen\fP(). |
|
59 |
.LP
|
|
60 |
The \fIdbm_close\fP() function shall close a database. The application |
|
61 |
shall ensure that argument \fIdb\fP is a pointer to a |
|
62 |
\fBdbm\fP structure that has been returned from a call to \fIdbm_open\fP(). |
|
63 |
.LP
|
|
64 |
These database functions shall support an internal block size large |
|
65 |
enough to support key/content pairs of at least 1023 |
|
66 |
bytes. |
|
67 |
.LP
|
|
68 |
The \fIdbm_fetch\fP() function shall read a record from a database. |
|
69 |
The argument \fIdb\fP is a pointer to a database structure |
|
70 |
that has been returned from a call to \fIdbm_open\fP(). The argument |
|
71 |
\fIkey\fP is a \fBdatum\fP that has been initialized by the |
|
72 |
application to the value of the key that matches the key of the record |
|
73 |
the program is fetching. |
|
74 |
.LP
|
|
75 |
The \fIdbm_store\fP() function shall write a record to a database. |
|
76 |
The argument \fIdb\fP is a pointer to a database structure |
|
77 |
that has been returned from a call to \fIdbm_open\fP(). The argument |
|
78 |
\fIkey\fP is a \fBdatum\fP that has been initialized by the |
|
79 |
application to the value of the key that identifies (for subsequent |
|
80 |
reading, writing, or deleting) the record the application is |
|
81 |
writing. The argument \fIcontent\fP is a \fBdatum\fP that has been |
|
82 |
initialized by the application to the value of the record the |
|
83 |
program is writing. The argument \fIstore_mode\fP controls whether |
|
84 |
\fIdbm_store\fP() replaces any pre-existing record that has |
|
85 |
the same key that is specified by the \fIkey\fP argument. The application |
|
86 |
shall set \fIstore_mode\fP to either DBM_INSERT or |
|
87 |
DBM_REPLACE. If the database contains a record that matches the \fIkey\fP |
|
88 |
argument and \fIstore_mode\fP is DBM_REPLACE, the |
|
89 |
existing record shall be replaced with the new record. If the database |
|
90 |
contains a record that matches the \fIkey\fP argument and |
|
91 |
\fIstore_mode\fP is DBM_INSERT, the existing record shall be left |
|
92 |
unchanged and the new record ignored. If the database does not |
|
93 |
contain a record that matches the \fIkey\fP argument and \fIstore_mode\fP |
|
94 |
is either DBM_INSERT or DBM_REPLACE, the new record |
|
95 |
shall be inserted in the database. |
|
96 |
.LP
|
|
97 |
If the sum of a key/content pair exceeds the internal block size, |
|
98 |
the result is unspecified. Moreover, the application shall |
|
99 |
ensure that all key/content pairs that hash together fit on a single |
|
100 |
block. The \fIdbm_store\fP() function shall return an error |
|
101 |
in the event that a disk block fills with inseparable data. |
|
102 |
.LP
|
|
103 |
The \fIdbm_delete\fP() function shall delete a record and its key |
|
104 |
from the database. The argument \fIdb\fP is a pointer to a |
|
105 |
database structure that has been returned from a call to \fIdbm_open\fP(). |
|
106 |
The argument \fIkey\fP is a \fBdatum\fP that has been |
|
107 |
initialized by the application to the value of the key that identifies |
|
108 |
the record the program is deleting. |
|
109 |
.LP
|
|
110 |
The \fIdbm_firstkey\fP() function shall return the first key in the |
|
111 |
database. The argument \fIdb\fP is a pointer to a database |
|
112 |
structure that has been returned from a call to \fIdbm_open\fP(). |
|
113 |
.LP
|
|
114 |
The \fIdbm_nextkey\fP() function shall return the next key in the |
|
115 |
database. The argument \fIdb\fP is a pointer to a database |
|
116 |
structure that has been returned from a call to \fIdbm_open\fP(). |
|
117 |
The application shall ensure that the \fIdbm_firstkey\fP() |
|
118 |
function is called before calling \fIdbm_nextkey\fP(). Subsequent |
|
119 |
calls to \fIdbm_nextkey\fP() return the next key until all of |
|
120 |
the keys in the database have been returned. |
|
121 |
.LP
|
|
122 |
The \fIdbm_error\fP() function shall return the error condition of |
|
123 |
the database. The argument \fIdb\fP is a pointer to a |
|
124 |
database structure that has been returned from a call to \fIdbm_open\fP(). |
|
125 |
.LP
|
|
126 |
The \fIdbm_clearerr\fP() function shall clear the error condition |
|
127 |
of the database. The argument \fIdb\fP is a pointer to a |
|
128 |
database structure that has been returned from a call to \fIdbm_open\fP(). |
|
129 |
.LP
|
|
130 |
The \fIdptr\fP pointers returned by these functions may point into |
|
131 |
static storage that may be changed by subsequent calls. |
|
132 |
.LP
|
|
133 |
These functions need not be reentrant. A function that is not required |
|
134 |
to be reentrant is not required to be thread-safe. |
|
135 |
.SH RETURN VALUE |
|
136 |
.LP
|
|
137 |
The \fIdbm_store\fP() and \fIdbm_delete\fP() functions shall return |
|
138 |
0 when they succeed and a negative value when they |
|
139 |
fail. |
|
140 |
.LP
|
|
141 |
The \fIdbm_store\fP() function shall return 1 if it is called with |
|
142 |
a \fIflags\fP value of DBM_INSERT and the function finds an |
|
143 |
existing record with the same key. |
|
144 |
.LP
|
|
145 |
The \fIdbm_error\fP() function shall return 0 if the error condition |
|
146 |
is not set and return a non-zero value if the error |
|
147 |
condition is set. |
|
148 |
.LP
|
|
149 |
The return value of \fIdbm_clearerr\fP() is unspecified. |
|
150 |
.LP
|
|
151 |
The \fIdbm_firstkey\fP() and \fIdbm_nextkey\fP() functions shall return |
|
152 |
a key \fBdatum\fP. When the end of the database is |
|
153 |
reached, the \fIdptr\fP member of the key is a null pointer. If an |
|
154 |
error is detected, the \fIdptr\fP member of the key shall be a |
|
155 |
null pointer and the error condition of the database shall be set. |
|
156 |
.LP
|
|
157 |
The \fIdbm_fetch\fP() function shall return a content \fBdatum\fP. |
|
158 |
If no record in the database matches the key or if an error |
|
159 |
condition has been detected in the database, the \fIdptr\fP member |
|
160 |
of the content shall be a null pointer. |
|
161 |
.LP
|
|
162 |
The \fIdbm_open\fP() function shall return a pointer to a database |
|
163 |
structure. If an error is detected during the operation, |
|
164 |
\fIdbm_open\fP() shall return a ( \fBDBM *\fP)0. |
|
165 |
.SH ERRORS |
|
166 |
.LP
|
|
167 |
No errors are defined. |
|
168 |
.LP
|
|
169 |
\fIThe following sections are informative.\fP |
|
170 |
.SH EXAMPLES |
|
171 |
.LP
|
|
172 |
None. |
|
173 |
.SH APPLICATION USAGE |
|
174 |
.LP
|
|
175 |
The following code can be used to traverse the database: |
|
176 |
.sp
|
|
177 |
.RS
|
|
178 |
.nf
|
|
179 |
||
180 |
\fBfor(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))
|
|
181 |
\fP
|
|
182 |
.fi
|
|
183 |
.RE
|
|
184 |
.LP
|
|
185 |
The \fIdbm_\fP* functions provided in this library should not be confused |
|
186 |
in any way with those of a general-purpose database |
|
187 |
management system. These functions do not provide for multiple search |
|
188 |
keys per entry, they do not protect against multi-user access |
|
189 |
(in other words they do not lock records or files), and they do not |
|
190 |
provide the many other useful database functions that are found |
|
191 |
in more robust database management systems. Creating and updating |
|
192 |
databases by use of these functions is relatively slow because of |
|
193 |
data copies that occur upon hash collisions. These functions are useful |
|
194 |
for applications requiring fast lookup of relatively static |
|
195 |
information that is to be indexed by a single key. |
|
196 |
.LP
|
|
197 |
Note that a strictly conforming application is extremely limited by |
|
198 |
these functions: since there is no way to determine that the |
|
199 |
keys in use do not all hash to the same value (although that would |
|
200 |
be rare), a strictly conforming application cannot be guaranteed |
|
201 |
that it can store more than one block's worth of data in the database. |
|
202 |
As long as a key collision does not occur, additional data |
|
203 |
may be stored, but because there is no way to determine whether an |
|
204 |
error is due to a key collision or some other error condition ( |
|
205 |
\fIdbm_error\fP() being effectively a Boolean), once an error is detected, |
|
206 |
the application is effectively limited to guessing what |
|
207 |
the error might be if it wishes to continue using these functions. |
|
208 |
.LP
|
|
209 |
The \fIdbm_delete\fP() function need not physically reclaim file space, |
|
210 |
although it does make it available for reuse by the |
|
211 |
database. |
|
212 |
.LP
|
|
213 |
After calling \fIdbm_store\fP() or \fIdbm_delete\fP() during a pass |
|
214 |
through the keys by \fIdbm_firstkey\fP() and |
|
215 |
\fIdbm_nextkey\fP(), the application should reset the database by |
|
216 |
calling \fIdbm_firstkey\fP() before again calling |
|
217 |
\fIdbm_nextkey\fP(). The contents of these files are unspecified and |
|
218 |
may not be portable. |
|
219 |
.SH RATIONALE |
|
220 |
.LP
|
|
221 |
None. |
|
222 |
.SH FUTURE DIRECTIONS |
|
223 |
.LP
|
|
224 |
None. |
|
225 |
.SH SEE ALSO |
|
226 |
.LP
|
|
227 |
\fIopen\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, |
|
228 |
\fI<ndbm.h>\fP |
|
229 |
.SH COPYRIGHT |
|
230 |
Portions of this text are reprinted and reproduced in electronic form |
|
231 |
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology |
|
232 |
-- Portable Operating System Interface (POSIX), The Open Group Base |
|
233 |
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of |
|
234 |
Electrical and Electronics Engineers, Inc and The Open Group. In the |
|
235 |
event of any discrepancy between this version and the original IEEE and |
|
236 |
The Open Group Standard, the original IEEE and The Open Group Standard |
|
237 |
is the referee document. The original Standard can be obtained online at |
|
238 |
http://www.opengroup.org/unix/online.html . |