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