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 July 7, 1999 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.Aq Pa ndbm.h : 69.Bd -literal 70typedef struct { 71 char *dptr; 72 int dsize; 73} datum; 74.Ed 75.Pp 76.Fn dbm_open base flags mode 77opens or creates a database. 78.Fa base 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 . 89.Fa flags 90and 91.Fa mode 92are passed to 93.Xr open 2 . 94.Pq Dv O_RDWR | O_CREAT 95is a typical value for 96.Fa flags ; 97.Li 0660 98is a typical value for 99.Fa mode . 100.Dv O_WRONLY 101is not allowed in 102.Fa flags . 103The pointer returned by 104.Fn dbm_open 105identifies the database and is the 106.Fa db 107argument to the other functions. 108.Fn dbm_open 109returns 110.Dv NULL 111and sets 112.Va errno 113if there were any errors. 114.Pp 115.Fn dbm_close db 116closes the database. 117.Fn dbm_close 118normally returns zero. 119.Pp 120.Fn dbm_store db key data flags 121inserts or replaces an entry in the database. 122.Fa flags 123is either 124.Dv DBM_INSERT 125or 126.Dv DBM_REPLACE . 127If 128.Fa flags 129is 130.Dv DBM_INSERT 131and the database already contains an entry for 132.Fa key , 133that entry is not replaced. 134Otherwise the entry is replaced or inserted. 135.Fn dbm_store 136normally returns zero but returns 1 if the entry could not be 137inserted (because 138.Fa flags 139is 140.Dv DBM_INSERT , 141and an entry with 142.Fa key 143already exists) or returns -1 and sets 144.Va errno 145if there were any errors. 146.Pp 147.Fn dbm_fetch db key 148returns 149.Dv NULL 150or the 151.Fa data 152corresponding to 153.Fa key . 154.Pp 155.Fn dbm_delete db key 156deletes the entry for 157.Fa key . 158.Fn dbm_delete 159normally returns zero but returns 1 if there was no entry with 160.Fa key 161in the database or returns -1 and sets 162.Va errno 163if there were any errors. 164.Pp 165.Fn dbm_firstkey db 166returns the first key in the database. 167.Fn dbm_nextkey db 168returns subsequent keys. 169.Fn db_firstkey 170must be called before 171.Fn dbm_nextkey . 172The order in which keys are returned is unspecified and may appear 173random. 174.Fn dbm_nextkey 175returns 176.Dv NULL 177after all keys have been returned. 178.Pp 179.Fn dbm_error db 180returns the 181.Va errno 182value of the most recent error. 183.Fn dbm_clearerr db 184resets this value to 0 and returns 0. 185.Pp 186.Fn dbm_dirfno db 187returns the file descriptor to the database. 188.Sh SEE ALSO 189.Xr open 2 , 190.Xr dbopen 3 , 191.Xr hash 3 192.Sh STANDARDS 193These functions (except 194.Fn dbm_dirfno ) 195are included in the 196.St -susv2 . 197