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 April 2, 2022 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 . 102.Dv O_WRONLY 103is not allowed in 104.Fa flags . 105The pointer returned by 106.Fn dbm_open 107identifies the database and is the 108.Fa db 109argument to the other functions. 110The 111.Fn dbm_open 112function 113returns 114.Dv NULL 115and sets 116.Va errno 117if there were any errors. 118.Pp 119The 120.Fn dbm_close db 121function 122closes the database. 123.Pp 124The 125.Fn dbm_store db key data flags 126function 127inserts or replaces an entry in the database. 128The 129.Fa flags 130argument 131is either 132.Dv DBM_INSERT 133or 134.Dv DBM_REPLACE . 135If 136.Fa flags 137is 138.Dv DBM_INSERT 139and the database already contains an entry for 140.Fa key , 141that entry is not replaced. 142Otherwise the entry is replaced or inserted. 143The 144.Fn dbm_store 145function 146normally returns zero but returns 1 if the entry could not be 147inserted (because 148.Fa flags 149is 150.Dv DBM_INSERT , 151and an entry with 152.Fa key 153already exists) or returns -1 and sets 154.Va errno 155if there were any errors. 156.Pp 157The 158.Fn dbm_fetch db key 159function 160returns 161.Dv NULL 162or the 163.Fa data 164corresponding to 165.Fa key . 166.Pp 167The 168.Fn dbm_delete db key 169function 170deletes the entry for 171.Fa key . 172The 173.Fn dbm_delete 174function 175normally returns zero or returns -1 and sets 176.Va errno 177if there were any errors. 178.Pp 179The 180.Fn dbm_firstkey db 181function 182returns the first key in the database. 183The 184.Fn dbm_nextkey db 185function 186returns subsequent keys. 187The 188.Fn db_firstkey 189function 190must be called before 191.Fn dbm_nextkey . 192The order in which keys are returned is unspecified and may appear 193random. 194The 195.Fn dbm_nextkey 196function 197returns 198.Dv NULL 199after all keys have been returned. 200.Pp 201The 202.Fn dbm_error db 203function 204returns the 205.Va errno 206value of the most recent error. 207The 208.Fn dbm_clearerr db 209function 210resets this value to 0 and returns 0. 211.Pp 212The 213.Fn dbm_dirfno db 214function 215returns the file descriptor to the database. 216.Sh SEE ALSO 217.Xr open 2 , 218.Xr dbopen 3 , 219.Xr hash 3 220.Sh STANDARDS 221These functions (except 222.Fn dbm_dirfno ) 223are included in the 224.St -susv2 . 225.Sh HISTORY 226The functions 227.Fn dbminit , 228.Fn fetch , 229.Fn store , 230.Fn delete , 231.Fn firstkey , 232and 233.Fn nextkey 234first appeared in 235.At v7 . 236