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