| blob | 5bb8757f27eac3577e5245e2c5d3d8cc9f5b2b7e |
1 .\" $NetBSD: dbm_clearerr.3,v 1.3 2004/05/06 19:16:32 wiz Exp $
2 .\"
3 .\" Copyright (c) 2004 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Klaus Klein.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd April 30, 2004
31 .Dt DBM_CLEARERR 3
32 .Os
33 .Sh NAME
34 .Nm dbm_clearerr ,
35 .Nm dbm_close ,
36 .Nm dbm_delete ,
37 .Nm dbm_dirfno ,
38 .Nm dbm_error ,
39 .Nm dbm_fetch ,
40 .Nm dbm_firstkey ,
41 .Nm dbm_nextkey ,
42 .Nm dbm_open ,
43 .Nm dbm_store ,
44 .Nm ndbm
45 .Nd database functions
46 .Sh LIBRARY
47 .Lb libc
48 .Sh SYNOPSIS
49 .In ndbm.h
50 .Ft int
51 .Fn dbm_clearerr "DBM *db"
52 .Ft void
53 .Fn dbm_close "DBM *db"
54 .Ft int
55 .Fn dbm_delete "DBM *db" "datum key"
56 .Ft int
57 .Fn dbm_dirfno "DBM *db"
58 .Ft int
59 .Fn dbm_error "DBM *db"
60 .Ft datum
61 .Fn dbm_fetch "DBM *db" "datum key"
62 .Ft datum
63 .Fn dbm_firstkey "DBM *db"
64 .Ft datum
65 .Fn dbm_nextkey "DBM *db"
66 .Ft DBM *
67 .Fn dbm_open "const char *file" "int open_flags" "mode_t file_mode"
68 .Ft int
69 .Fn dbm_store "DBM *db" "datum key" "datum content" "int store_mode"
70 .Sh DESCRIPTION
71 The
72 .Nm ndbm
73 facility provides access to hash database files.
74 .Pp
75 Two data types are fundamental to the
76 .Nm ndbm
77 facility.
78 .Fa DBM
79 serves as a handle to a database.
80 It is an opaque type.
81 .Pp
82 The other data type is
83 .Fa datum ,
84 which is a structure type which includes the following members:
85 .Bd -literal -offset indent
86 void * dptr
87 size_t dsize
88 .Ed
89 .Pp
90 A
91 .Fa datum
92 is thus given by
93 .Fa dptr
94 pointing at an object of
95 .Fa dsize
96 bytes in length.
97 .Pp
98 The
99 .Fn dbm_open
100 function opens a database.
101 The
102 .Fa file
103 argument is the pathname which the actual database file pathname
104 is based on.
105 This implementation uses a single file with the suffix
106 .Pa .db
107 appended to
108 .Fa file .
109 The
110 .Fa open_flags
111 argument has the same meaning as the
112 .Fa flags
113 argument to
114 .Xr open 2
115 except that when opening a database for write-only access the file
116 is opened for read/write access, and the
117 .Dv O_APPEND
118 flag must not be specified.
119 The
120 .Fa file_mode
121 argument has the same meaning as the
122 .Fa mode
123 argument to
124 .Xr open 2 .
125 .Pp
126 For the following functions, the
127 .Fa db
128 argument is a handle previously returned by a call to
129 .Fn dbm_open .
130 .Pp
131 The
132 .Fn dbm_close
133 function closes a database.
134 .Pp
135 The
136 .Fn dbm_fetch
137 function retrieves a record from the database.
138 The
139 .Fa key
140 argument is a
141 .Fa datum
142 that identifies the record to be fetched.
143 .Pp
144 The
145 .Fn dbm_store
146 function stores a record into the database.
147 The
148 .Fa key
149 argument is a
150 .Fa datum
151 that identifies the record to be stored.
152 The
153 .Fa content
154 argument is a
155 .Fa datum
156 that specifies the value of the record to be stored.
157 The
158 .Fa store_mode
159 argument specifies the behavior of
160 .Fn dbm_store
161 if a record matching
162 .Fa key
163 is already present in the database,
164 .Fa db .
165 .Fa store_mode
166 must be one of the following:
167 .Bl -tag -width DBM_REPLACEXX -offset indent
168 .It Dv DBM_INSERT
169 If a record matching
170 .Fa key
171 is already present, it is left unchanged.
172 .It Dv DBM_REPLACE
173 If a record matching
174 .Fa key
175 is already present, its value is replaced by
176 .Fa content .
177 .El
178 .Pp
179 If no record matching
180 .Fa key
181 is present, a new record is inserted regardless of
182 .Fa store_mode .
183 .Pp
184 The
185 .Fn dbm_delete
186 function deletes a record from the database.
187 The
188 .Fa key
189 argument is a
190 .Fa datum
191 that identifies the record to be deleted.
192 .Pp
193 The
194 .Fn dbm_firstkey
195 function returns the first key in the database.
196 .Pp
197 The
198 .Fn dbm_nextkey
199 function returns the next key in the database.
200 In order to be meaningful, it must be preceded by a call to
201 .Fn dbm_firstkey .
202 .Pp
203 The
204 .Fn dbm_error
205 function returns the error indicator of the database.
206 .Pp
207 The
208 .Fn dbm_clearerr
209 function clears the error indicator of the database.
210 .Pp
211 The
212 .Fn dbm_dirfno
213 function returns the file descriptor of the underlying database file.
214 .Sh IMPLEMENTATION NOTES
215 The
216 .Nm ndbm
217 facility is implemented on top of the
218 .Xr hash 3
219 access method of the
220 .Xr db 3
221 database facility.
222 .Sh RETURN VALUES
223 The
224 .Fn dbm_open
225 function returns a pointer to a
226 .Fa DBM
227 when successful; otherwise a null pointer is returned.
228 .Pp
229 The
230 .Fn dbm_close
231 function returns no value.
232 .Pp
233 The
234 .Fn dbm_fetch
235 function returns a content
236 .Fa datum ;
237 if no record matching
238 .Fa key
239 was found or if an error occured, its
240 .Fa dptr
241 member is a null pointer.
242 .Pp
243 The
244 .Fn dbm_store
245 function returns 0 when then record was successfully inserted;
246 it returns 1 when called with
247 .Fa store_mode
248 being
249 .Dv DBM_INSERT
250 and a record matching
251 .Fa key
252 is already present;
253 otherwise a negative value is returned.
254 .Pp
255 The
256 .Fn dbm_delete
257 function returns 0 when the record was successfully deleted;
258 otherwise a negative value is returned.
259 .Pp
260 The
261 .Fn dbm_firstkey
262 and
263 .Fn dbm_nextkey
264 functions return a key
265 .Fa datum .
266 When the end of the database is reached or if an error occured, its
267 .Fa dptr
268 member is a null pointer.
269 .Pp
270 The
271 .Fn dbm_error
272 function returns 0 if the error indicator is clear;
273 if the error indicator is set a non-zero value is returned.
274 .Pp
275 The
276 .Fn dbm_clearerr
277 function always returns 0.
278 .Pp
279 The
280 .Fn dbm_dirfno
281 function returns the file descriptor of the underlying database file.
282 .Sh ERRORS
283 No errors are defined.
284 .Sh SEE ALSO
285 .Xr open 2 ,
286 .Xr db 3 ,
287 .Xr hash 3
288 .Sh STANDARDS
289 The
290 .Fn dbm_clearerr ,
291 .Fn dbm_close ,
292 .Fn dbm_delete ,
293 .Fn dbm_error ,
294 .Fn dbm_fetch ,
295 .Fn dbm_firstkey ,
296 .Fn dbm_nextkey ,
297 .Fn dbm_open ,
298 and
299 .Fn dbm_store
300 functions conform to
301 .St -xpg4.2 .
302 The
303 .Fn dbm_dirfno
304 function is an extension.