1.\" Copyright (c) 1999 Tim Singletary 2.\" No copyright is claimed. 3.\" 4.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 5.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 6.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 7.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 8.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 9.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 10.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 11.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 12.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 13.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 14.\" SUCH DAMAGE. 15.\" 16.\" $FreeBSD$ 17.\" 18.\" Note: The date here should be updated whenever a non-trivial 19.\" change is made to the manual page. 20.Dd July 7, 1999 21.Dt DBM 3 22.Os 23.Sh NAME 24.Nm dbm_clearerr , 25.Nm dbm_close , 26.Nm dbm_delete , 27.Nm dbm_dirfno , 28.Nm dbm_error , 29.Nm dbm_fetch , 30.Nm dbm_firstkey , 31.Nm dbm_nextkey , 32.Nm dbm_open , 33.Nm dbm_store 34.Nd database access functions 35.Sh SYNOPSIS 36.In fcntl.h 37.In ndbm.h 38.Ft DBM * 39.Fn dbm_open "const char *base" "int flags" "int mode" 40.Ft void 41.Fn dbm_close "DBM *db" 42.Ft int 43.Fn dbm_store "DBM *db" "datum key" "datum data" "int flags" 44.Ft datum 45.Fn dbm_fetch "DBM *db" "datum key" 46.Ft int 47.Fn dbm_delete "DBM *db" "datum key" 48.Ft datum 49.Fn dbm_firstkey "DBM *db" 50.Ft datum 51.Fn dbm_nextkey "DBM *db" 52.Ft int 53.Fn dbm_error "DBM *db" 54.Ft int 55.Fn dbm_clearerr "DBM *db" 56.Ft int 57.Fn dbm_dirfno "DBM *db" 58.Sh DESCRIPTION 59Database access functions. 60These functions are implemented using 61.Xr dbopen 3 62with a 63.Xr hash 3 64database. 65.Pp 66.Vt datum 67is declared in 68.In ndbm.h : 69.Bd -literal 70typedef struct { 71 char *dptr; 72 int dsize; 73} datum; 74.Ed 75.Pp 76The 77.Fn dbm_open base flags mode 78function 79opens or creates a database. 80The 81.Fa base 82argument 83is the basename of the file containing 84the database; the actual database has a 85.Pa .db 86suffix. 87I.e., if 88.Fa base 89is 90.Qq Li /home/me/mystuff 91then the actual database is in the file 92.Pa /home/me/mystuff.db . 93The 94.Fa flags 95and 96.Fa mode 97arguments 98are passed to 99.Xr open 2 . 100.Pq Dv O_RDWR | O_CREAT 101is a typical value for 102.Fa flags ; 103.Li 0660 104is a typical value for 105.Fa mode . 106.Dv O_WRONLY 107is not allowed in 108.Fa flags . 109The pointer returned by 110.Fn dbm_open 111identifies the database and is the 112.Fa db 113argument to the other functions. 114The 115.Fn dbm_open 116function 117returns 118.Dv NULL 119and sets 120.Va errno 121if there were any errors. 122.Pp 123The 124.Fn dbm_close db 125function 126closes the database. 127The 128.Fn dbm_close 129function 130normally returns zero. 131.Pp 132The 133.Fn dbm_store db key data flags 134function 135inserts or replaces an entry in the database. 136The 137.Fa flags 138argument 139is either 140.Dv DBM_INSERT 141or 142.Dv DBM_REPLACE . 143If 144.Fa flags 145is 146.Dv DBM_INSERT 147and the database already contains an entry for 148.Fa key , 149that entry is not replaced. 150Otherwise the entry is replaced or inserted. 151The 152.Fn dbm_store 153function 154normally returns zero but returns 1 if the entry could not be 155inserted (because 156.Fa flags 157is 158.Dv DBM_INSERT , 159and an entry with 160.Fa key 161already exists) or returns -1 and sets 162.Va errno 163if there were any errors. 164.Pp 165The 166.Fn dbm_fetch db key 167function 168returns 169.Dv NULL 170or the 171.Fa data 172corresponding to 173.Fa key . 174.Pp 175The 176.Fn dbm_delete db key 177function 178deletes the entry for 179.Fa key . 180The 181.Fn dbm_delete 182function 183normally returns zero but returns 1 if there was no entry with 184.Fa key 185in the database or returns -1 and sets 186.Va errno 187if there were any errors. 188.Pp 189The 190.Fn dbm_firstkey db 191function 192returns the first key in the database. 193The 194.Fn dbm_nextkey db 195function 196returns subsequent keys. 197The 198.Fn db_firstkey 199function 200must be called before 201.Fn dbm_nextkey . 202The order in which keys are returned is unspecified and may appear 203random. 204The 205.Fn dbm_nextkey 206function 207returns 208.Dv NULL 209after all keys have been returned. 210.Pp 211The 212.Fn dbm_error db 213function 214returns the 215.Va errno 216value of the most recent error. 217The 218.Fn dbm_clearerr db 219function 220resets this value to 0 and returns 0. 221.Pp 222The 223.Fn dbm_dirfno db 224function 225returns the file descriptor to the database. 226.Sh SEE ALSO 227.Xr open 2 , 228.Xr dbopen 3 , 229.Xr hash 3 230.Sh STANDARDS 231These functions (except 232.Fn dbm_dirfno ) 233are included in the 234.St -susv2 . 235