lib/libc/db/man/dbm.3

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