1.\" $NetBSD: dbm_clearerr.3,v 1.5 2010/05/05 06:55:57 jruoho 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 May 5, 2010 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 71The 72.Nm ndbm 73facility provides access to hash database files. 74.Pp 75Two data types are fundamental to the 76.Nm ndbm 77facility. 78.Fa DBM 79serves as a handle to a database. 80It is an opaque type. 81.Pp 82The other data type is 83.Fa datum , 84which is a structure type which includes the following members: 85.Bd -literal -offset indent 86void * dptr 87size_t dsize 88.Ed 89.Pp 90A 91.Fa datum 92is thus given by 93.Fa dptr 94pointing at an object of 95.Fa dsize 96bytes in length. 97.Pp 98The 99.Fn dbm_open 100function opens a database. 101The 102.Fa file 103argument is the pathname which the actual database file pathname 104is based on. 105This implementation uses a single file with the suffix 106.Pa .db 107appended to 108.Fa file . 109The 110.Fa open_flags 111argument has the same meaning as the 112.Fa flags 113argument to 114.Xr open 2 115except that when opening a database for write-only access the file 116is opened for read/write access, and the 117.Dv O_APPEND 118flag must not be specified. 119The 120.Fa file_mode 121argument has the same meaning as the 122.Fa mode 123argument to 124.Xr open 2 . 125.Pp 126For the following functions, the 127.Fa db 128argument is a handle previously returned by a call to 129.Fn dbm_open . 130.Pp 131The 132.Fn dbm_close 133function closes a database. 134.Pp 135The 136.Fn dbm_fetch 137function retrieves a record from the database. 138The 139.Fa key 140argument is a 141.Fa datum 142that identifies the record to be fetched. 143.Pp 144The 145.Fn dbm_store 146function stores a record into the database. 147The 148.Fa key 149argument is a 150.Fa datum 151that identifies the record to be stored. 152The 153.Fa content 154argument is a 155.Fa datum 156that specifies the value of the record to be stored. 157The 158.Fa store_mode 159argument specifies the behavior of 160.Fn dbm_store 161if a record matching 162.Fa key 163is already present in the database, 164.Fa db . 165.Fa store_mode 166must be one of the following: 167.Bl -tag -width DBM_REPLACEXX -offset indent 168.It Dv DBM_INSERT 169If a record matching 170.Fa key 171is already present, it is left unchanged. 172.It Dv DBM_REPLACE 173If a record matching 174.Fa key 175is already present, its value is replaced by 176.Fa content . 177.El 178.Pp 179If no record matching 180.Fa key 181is present, a new record is inserted regardless of 182.Fa store_mode . 183.Pp 184The 185.Fn dbm_delete 186function deletes a record from the database. 187The 188.Fa key 189argument is a 190.Fa datum 191that identifies the record to be deleted. 192.Pp 193The 194.Fn dbm_firstkey 195function returns the first key in the database. 196.Pp 197The 198.Fn dbm_nextkey 199function returns the next key in the database. 200In order to be meaningful, it must be preceded by a call to 201.Fn dbm_firstkey . 202.Pp 203The 204.Fn dbm_error 205function returns the error indicator of the database. 206.Pp 207The 208.Fn dbm_clearerr 209function clears the error indicator of the database. 210.Pp 211The 212.Fn dbm_dirfno 213function returns the file descriptor of the underlying database file. 214.Sh IMPLEMENTATION NOTES 215The 216.Nm ndbm 217facility is implemented on top of the 218.Xr hash 3 219access method of the 220.Xr db 3 221database facility. 222.Sh RETURN VALUES 223The 224.Fn dbm_open 225function returns a pointer to a 226.Fa DBM 227when successful; otherwise a null pointer is returned. 228.Pp 229The 230.Fn dbm_close 231function returns no value. 232.Pp 233The 234.Fn dbm_fetch 235function returns a content 236.Fa datum ; 237if no record matching 238.Fa key 239was found or if an error occured, its 240.Fa dptr 241member is a null pointer. 242.Pp 243The 244.Fn dbm_store 245function returns 0 when then record was successfully inserted; 246it returns 1 when called with 247.Fa store_mode 248being 249.Dv DBM_INSERT 250and a record matching 251.Fa key 252is already present; 253otherwise a negative value is returned. 254.Pp 255The 256.Fn dbm_delete 257function returns 0 when the record was successfully deleted; 258otherwise a negative value is returned. 259.Pp 260The 261.Fn dbm_firstkey 262and 263.Fn dbm_nextkey 264functions return a key 265.Fa datum . 266When the end of the database is reached or if an error occured, its 267.Fa dptr 268member is a null pointer. 269.Pp 270The 271.Fn dbm_error 272function returns 0 if the error indicator is clear; 273if the error indicator is set a non-zero value is returned. 274.Pp 275The 276.Fn dbm_clearerr 277function always returns 0. 278.Pp 279The 280.Fn dbm_dirfno 281function returns the file descriptor of the underlying database file. 282.Sh ERRORS 283No errors are defined. 284.Sh SEE ALSO 285.Xr open 2 , 286.Xr db 3 , 287.Xr hash 3 288.Sh STANDARDS 289The 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 , 298and 299.Fn dbm_store 300functions conform to 301.St -xpg4.2 302and 303.St -susv2 . 304The 305.Fn dbm_dirfno 306function is an extension. 307