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