db/man/FreeBSD/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: src/lib/libc/db/man/dbm.3,v 1.10 2009/01/30 15:28:35 gabor Exp $
  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 ndbm.h
  35 .Ft int
  36 .Fo dbm_clearerr
  37 .Fa "DBM *db"
  38 .Fc
  39 .Ft void
  40 .Fo dbm_close
  41 .Fa "DBM *db"
  42 .Fc
  43 .Ft int
  44 .Fo dbm_delete
  45 .Fa "DBM *db"
  46 .Fa "datum key"
  47 .Fc
  48 .Ft int
  49 .Fo dbm_dirfno
  50 .Fa "DBM *db"
  51 .Fc
  52 .Ft int
  53 .Fo dbm_error
  54 .Fa "DBM *db"
  55 .Fc
  56 .Ft datum
  57 .Fo dbm_fetch
  58 .Fa "DBM *db"
  59 .Fa "datum key"
  60 .Fc
  61 .Ft datum
  62 .Fo dbm_firstkey
  63 .Fa "DBM *db"
  64 .Fc
  65 .Ft datum
  66 .Fo dbm_nextkey
  67 .Fa "DBM *db"
  68 .Fc
  69 .Ft DBM *
  70 .Fo dbm_open
  71 .Fa "const char *file"
  72 .Fa "int open_flags"
  73 .Fa "mode_t file_mode"
  74 .Fc
  75 .Ft int
  76 .Fo dbm_store
  77 .Fa "DBM *db"
  78 .Fa "datum key"
  79 .Fa "datum content"
  80 .Fa "int store_mode"
  81 .Fc
  82 .Sh DESCRIPTION
  83 Database access functions.
  84 These functions are implemented using
  85 .Xr dbopen 3
  86 with a
  87 .Xr hash 3
  88 database.
  89 .Pp
  90 .Vt datum
  91 is declared in
  92 .In ndbm.h :
  93 .Bd -literal
  94 typedef struct {
  95         char *dptr;
  96         int dsize;
  97 } datum;
  98 .Ed
  99 .Pp
 100 The
 101 .Fn dbm_open file open_flags file_mode
 102 function
 103 opens or creates a database file.
 104 The
 105 .Fa file
 106 argument
 107 is the basename of the file containing
 108 the database; the actual database has a
 109 .Pa .db
 110 suffix.
 111 I.e., if
 112 .Fa file
 113 is
 114 .Qq Li /home/me/mystuff
 115 then the actual database is in the file
 116 .Pa /home/me/mystuff.db .
 117 The
 118 .Fa open_flags
 119 and
 120 .Fa file_mode
 121 arguments
 122 are passed to
 123 .Xr open 2 .
 124 .Pq Dv O_RDWR | O_CREAT
 125 is a typical value for
 126 .Fa open_flags ;
 127 .Li 0660
 128 is a typical value for
 129 .Fa file_mode .
 130 .Dv O_WRONLY
 131 is not allowed in
 132 .Fa open_flags .
 133 The pointer returned by
 134 .Fn dbm_open
 135 identifies the database and is the
 136 .Fa db
 137 argument to the other functions.
 138 The
 139 .Fn dbm_open
 140 function
 141 returns
 142 .Dv NULL
 143 and sets
 144 .Va errno
 145 if there were any errors.
 146 .Pp
 147 The
 148 .Fn dbm_close db
 149 function
 150 closes the database.
 151 .Pp
 152 The
 153 .Fn dbm_store db key content store_mode
 154 function
 155 inserts or replaces an entry in the database.
 156 The
 157 .Fa store_mode
 158 argument
 159 is either
 160 .Dv DBM_INSERT
 161 or
 162 .Dv DBM_REPLACE .
 163 If
 164 .Fa store_mode
 165 is
 166 .Dv DBM_INSERT
 167 and the database already contains an entry for
 168 .Fa key ,
 169 that entry is not replaced.
 170 Otherwise the entry is replaced or inserted.
 171 The
 172 .Fn dbm_store
 173 function
 174 normally returns zero but returns 1 if the entry could not be
 175 inserted (because
 176 .Fa store_mode
 177 is
 178 .Dv DBM_INSERT ,
 179 and an entry with
 180 .Fa key
 181 already exists) or returns -1 and sets
 182 .Va errno
 183 if there were any errors.
 184 .Pp
 185 The
 186 .Fn dbm_fetch db key
 187 function
 188 returns
 189 .Dv NULL
 190 or the
 191 .Fa content
 192 corresponding to
 193 .Fa key .
 194 .Pp
 195 The
 196 .Fn dbm_delete db key
 197 function
 198 deletes the entry for
 199 .Fa key .
 200 The
 201 .Fn dbm_delete
 202 function
 203 normally returns zero but returns 1 if there was no entry with
 204 .Fa key
 205 in the database or returns -1 and sets
 206 .Va errno
 207 if there were any errors.
 208 .Pp
 209 The
 210 .Fn dbm_firstkey db
 211 function
 212 returns the first key in the database.
 213 The
 214 .Fn dbm_nextkey db
 215 function
 216 returns subsequent keys.
 217 The
 218 .Fn db_firstkey
 219 function
 220 must be called before
 221 .Fn dbm_nextkey .
 222 The order in which keys are returned is unspecified and may appear
 223 random.
 224 The
 225 .Fn dbm_nextkey
 226 function
 227 returns
 228 .Dv NULL
 229 after all keys have been returned.
 230 .Pp
 231 The
 232 .Fn dbm_error db
 233 function
 234 returns the
 235 .Va errno
 236 value of the most recent error.
 237 The
 238 .Fn dbm_clearerr db
 239 function
 240 resets this value to 0 and returns 0.
 241 .Pp
 242 The
 243 .Fn dbm_dirfno db
 244 function
 245 returns the file descriptor to the database.
 246 .Sh LEGACY SYNOPSIS
 247 .Fd #include <fcntl.h>
 248 .Fd #include <ndbm.h>
 249 .Pp
 250 The include file
 251 .In ndbm.h
 252 is necessary for all functions.
 253 .Pp
 254 .Ft DBM *
 255 .br
 256 .Fo dbm_open
 257 .Fa "const char *file"
 258 .Fa "int open_flags"
 259 .Fa "int file_mode"
 260 .Fc ;
 261 .Pp
 262 .Fa file_mode
 263 has type
 264 .Vt int .
 265 .Sh SEE ALSO
 266 .Xr open 2 ,
 267 .Xr dbopen 3 ,
 268 .Xr hash 3 ,
 269 .Xr compat 5
 270 .Sh STANDARDS
 271 These functions (except
 272 .Fn dbm_dirfno )
 273 are included in the
 274 .St -susv2 .