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