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.Dd April 2, 2022 19.Dt DBM 3 20.Os 21.Sh NAME 22.Nm dbm_clearerr , 23.Nm dbm_close , 24.Nm dbm_delete , 25.Nm dbm_dirfno , 26.Nm dbm_error , 27.Nm dbm_fetch , 28.Nm dbm_firstkey , 29.Nm dbm_nextkey , 30.Nm dbm_open , 31.Nm dbm_store 32.Nd database access functions 33.Sh SYNOPSIS 34.In fcntl.h 35.In ndbm.h 36.Ft DBM * 37.Fn dbm_open "const char *base" "int flags" "mode_t mode" 38.Ft void 39.Fn dbm_close "DBM *db" 40.Ft int 41.Fn dbm_store "DBM *db" "datum key" "datum data" "int flags" 42.Ft datum 43.Fn dbm_fetch "DBM *db" "datum key" 44.Ft int 45.Fn dbm_delete "DBM *db" "datum key" 46.Ft datum 47.Fn dbm_firstkey "DBM *db" 48.Ft datum 49.Fn dbm_nextkey "DBM *db" 50.Ft int 51.Fn dbm_error "DBM *db" 52.Ft int 53.Fn dbm_clearerr "DBM *db" 54.Ft int 55.Fn dbm_dirfno "DBM *db" 56.Sh DESCRIPTION 57Database access functions. 58These functions are implemented using 59.Xr dbopen 3 60with a 61.Xr hash 3 62database. 63.Pp 64.Vt datum 65is declared in 66.In ndbm.h : 67.Bd -literal 68typedef struct { 69 void *dptr; 70 int dsize; 71} datum; 72.Ed 73.Pp 74The 75.Fn dbm_open base flags mode 76function 77opens or creates a database. 78The 79.Fa base 80argument 81is the basename of the file containing 82the database; the actual database has a 83.Pa .db 84suffix. 85I.e., if 86.Fa base 87is 88.Qq Li /home/me/mystuff 89then the actual database is in the file 90.Pa /home/me/mystuff.db . 91The 92.Fa flags 93and 94.Fa mode 95arguments 96are passed to 97.Xr open 2 . 98.Pq Dv O_RDWR | O_CREAT 99is a typical value for 100.Fa flags ; 101.Li 0660 102is a typical value for 103.Fa mode . 104.Dv O_WRONLY 105is not allowed in 106.Fa flags . 107The pointer returned by 108.Fn dbm_open 109identifies the database and is the 110.Fa db 111argument to the other functions. 112The 113.Fn dbm_open 114function 115returns 116.Dv NULL 117and sets 118.Va errno 119if there were any errors. 120.Pp 121The 122.Fn dbm_close db 123function 124closes the database. 125.Pp 126The 127.Fn dbm_store db key data flags 128function 129inserts or replaces an entry in the database. 130The 131.Fa flags 132argument 133is either 134.Dv DBM_INSERT 135or 136.Dv DBM_REPLACE . 137If 138.Fa flags 139is 140.Dv DBM_INSERT 141and the database already contains an entry for 142.Fa key , 143that entry is not replaced. 144Otherwise the entry is replaced or inserted. 145The 146.Fn dbm_store 147function 148normally returns zero but returns 1 if the entry could not be 149inserted (because 150.Fa flags 151is 152.Dv DBM_INSERT , 153and an entry with 154.Fa key 155already exists) or returns -1 and sets 156.Va errno 157if there were any errors. 158.Pp 159The 160.Fn dbm_fetch db key 161function 162returns 163.Dv NULL 164or the 165.Fa data 166corresponding to 167.Fa key . 168.Pp 169The 170.Fn dbm_delete db key 171function 172deletes the entry for 173.Fa key . 174The 175.Fn dbm_delete 176function 177normally returns zero or returns -1 and sets 178.Va errno 179if there were any errors. 180.Pp 181The 182.Fn dbm_firstkey db 183function 184returns the first key in the database. 185The 186.Fn dbm_nextkey db 187function 188returns subsequent keys. 189The 190.Fn db_firstkey 191function 192must be called before 193.Fn dbm_nextkey . 194The order in which keys are returned is unspecified and may appear 195random. 196The 197.Fn dbm_nextkey 198function 199returns 200.Dv NULL 201after all keys have been returned. 202.Pp 203The 204.Fn dbm_error db 205function 206returns the 207.Va errno 208value of the most recent error. 209The 210.Fn dbm_clearerr db 211function 212resets this value to 0 and returns 0. 213.Pp 214The 215.Fn dbm_dirfno db 216function 217returns the file descriptor to the database. 218.Sh SEE ALSO 219.Xr open 2 , 220.Xr dbopen 3 , 221.Xr hash 3 222.Sh STANDARDS 223These functions (except 224.Fn dbm_dirfno ) 225are included in the 226.St -susv2 . 227.Sh HISTORY 228The functions 229.Fn dbminit , 230.Fn fetch , 231.Fn store , 232.Fn delete , 233.Fn firstkey , 234and 235.Fn nextkey 236first appeared in 237.At v7 . 238