1.\" David Leonard, 1998. Placed in the public domain. 2.\" $OpenBSD: ndbm.3,v 1.20 2016/05/07 23:35:45 naddy Exp $ 3.Dd $Mdocdate: May 7 2016 $ 4.Dt DBM_OPEN 3 5.Os 6.Sh NAME 7.Nm dbm_clearerr , 8.Nm dbm_close , 9.Nm dbm_delete , 10.Nm dbm_dirfno , 11.Nm dbm_error , 12.Nm dbm_fetch , 13.Nm dbm_firstkey , 14.Nm dbm_nextkey , 15.Nm dbm_open , 16.Nm dbm_pagfno , 17.Nm dbm_rdonly , 18.Nm dbm_store 19.Nd database access methods 20.Sh SYNOPSIS 21.In ndbm.h 22.Ft int 23.Fn dbm_clearerr "DBM *db" 24.Ft void 25.Fn dbm_close "DBM *db" 26.Ft int 27.Fn dbm_delete "DBM *db" "datum key" 28.Ft int 29.Fn dbm_dirfno "DBM *db" 30.Ft int 31.Fn dbm_error "DBM *db" 32.Ft datum 33.Fn dbm_fetch "DBM *db" "datum key" 34.Ft datum 35.Fn dbm_firstkey "DBM *db" 36.Ft datum 37.Fn dbm_nextkey "DBM *db" 38.Ft "DBM *" 39.Fn dbm_open "const char *file" "int flags" "mode_t mode" 40.Ft int 41.Fn dbm_pagfno "DBM *db" 42.Ft int 43.Fn dbm_rdonly "DBM *db" 44.Ft int 45.Fn dbm_store "DBM *db" "datum key" "datum content" "int store_mode" 46.Sh DESCRIPTION 47These functions provide a ndbm-compatible interface to the 48database access methods described in 49.Xr dbopen 3 . 50Each unique record in the database is a key/content pair, 51the components of which may be any arbitrary binary data. 52The key and the content data are described by the 53.Ft datum 54data structure: 55.Bd -literal -offset indent 56typedef struct { 57 void *dptr; 58 size_t dsize; 59} datum; 60.Ed 61.Pp 62The 63.Fn dbm_open 64function is used to open a database in the file named by 65.Fa file , 66suffixed with 67.Dv DBM_SUFFIX 68.Pq Sq Pa .db . 69If necessary, the file is created with mode 70.Ar mode . 71Access to this file depends on the 72.Fa flags 73parameter (see 74.Xr open 2 ) . 75Read-only access may be indicated by specifying 76.Dv DBM_RDONLY . 77The 78.Fn dbm_rdonly 79function may be used to determine if a database is opened for read-only 80access. 81.Pp 82Once the database is open, 83.Fn dbm_fetch 84is used to retrieve the data content associated with the key 85.Fa key . 86Similarly, 87.Fn dbm_store 88is used to store the 89.Fa content 90data with the key 91.Fa key . 92When storing, the 93.Fa store_mode 94parameter must be one of: 95.Bl -tag -width DBM_REPLACE -offset indent 96.It Dv DBM_INSERT 97Only insert new keys into the database. 98Existing key/content pairs are untouched. 99.It Dv DBM_REPLACE 100Replace any existing entry with the same key. 101Any previously stored records with the same key are lost. 102.El 103.Pp 104The 105.Fn dbm_delete 106function removes the key 107.Fa key 108and its associated content from the database. 109.Pp 110The functions 111.Fn dbm_firstkey 112and 113.Fn dbm_nextkey 114are used to iterate over all of the records in the database. 115Each record will be reached exactly once, but in no particular order. 116The 117.Fn dbm_firstkey 118function returns the first record of the database, and thereafter 119.Fn dbm_nextkey 120returns the following records. 121The following code traverses the entire database: 122.Bd -literal -offset indent 123for (key = dbm_firstkey(db); key.dptr != NULL; 124 key = dbm_nextkey(db)) 125.Ed 126.Pp 127The behaviour of 128.Fn dbm_nextkey 129is undefined if the database is modified after a call to 130.Fn dbm_firstkey . 131.Pp 132The 133.Fn dbm_error 134function returns the last error condition of the database, 135or 0 if no error had occurred or had been cleared. 136The 137.Fn dbm_clearerr 138function clears the error condition of the database. 139.Pp 140The 141.Fn dbm_dirfno 142function is used to find the file descriptor associated with the 143directory file of an open database. 144Since a directory bitmap file is not used in this implementation, 145this function returns the file descriptor of the database file opened with 146.Fn dbm_open . 147.Pp 148The 149.Fn dbm_pagfno 150function is used to find the file descriptor associated with the 151page file of an open database. 152Since a page file is not used in this implementation, this function 153is implemented as a macro that always returns the (undefined) value 154.Dv DBM_PAGFNO_NOT_AVAILABLE . 155.Pp 156The database is closed with the 157.Fn dbm_close 158function. 159Thereafter, the 160.Fa db 161handle is invalid. 162.Ss Implementation notes 163The underlying database is a 164.Xr hash 3 165database with a 166bucket size of 4096, 167a filling factor of 40, 168default hashing function and cache size, 169and uses the host's native byte order. 170.Sh RETURN VALUES 171Upon successful completion, all functions that return 172.Ft int 173return a value of 0, otherwise a negative value is returned. 174.Pp 175Routines that return a 176.Ft datum 177indicate errors by setting the 178.Va dptr 179field to 180.Dv NULL . 181.Pp 182The 183.Fn dbm_open 184function returns 185.Dv NULL 186on error, and sets 187.Va errno 188appropriately. 189On success, it returns a handle to the database that should be 190used as the 191.Fa db 192argument in the other functions. 193.Pp 194The 195.Fn dbm_store 196function returns 1 when it is called with a 197.Fa flags 198value of 199.Dv DBM_INSERT 200and a record with the specified key already exists. 201.Sh ERRORS 202If an error occurs, the error can be retrieved with 203.Fn dbm_error 204and corresponds to those errors described in 205.Xr dbopen 3 . 206.Sh SEE ALSO 207.Xr open 2 , 208.Xr dbopen 3 , 209.Xr hash 3 210