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