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 16, 2006 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" "int 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 char *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 but returns 1 if there was no entry with 178.Fa key 179in the database or returns -1 and sets 180.Va errno 181if there were any errors. 182.Pp 183The 184.Fn dbm_firstkey db 185function 186returns the first key in the database. 187The 188.Fn dbm_nextkey db 189function 190returns subsequent keys. 191The 192.Fn db_firstkey 193function 194must be called before 195.Fn dbm_nextkey . 196The order in which keys are returned is unspecified and may appear 197random. 198The 199.Fn dbm_nextkey 200function 201returns 202.Dv NULL 203after all keys have been returned. 204.Pp 205The 206.Fn dbm_error db 207function 208returns the 209.Va errno 210value of the most recent error. 211The 212.Fn dbm_clearerr db 213function 214resets this value to 0 and returns 0. 215.Pp 216The 217.Fn dbm_dirfno db 218function 219returns the file descriptor to the database. 220.Sh SEE ALSO 221.Xr open 2 , 222.Xr dbopen 3 , 223.Xr hash 3 224.Sh STANDARDS 225These functions (except 226.Fn dbm_dirfno ) 227are included in the 228.St -susv2 . 229