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