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.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 fcntl.h
  37 .In ndbm.h
  38 .Ft DBM *
  39 .Fn dbm_open "const char *base" "int flags" "int 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 The
 128 .Fn dbm_close
 129 function
 130 normally returns zero.
 131 .Pp
 132 The
 133 .Fn dbm_store db key data flags
 134 function
 135 inserts or replaces an entry in the database.
 136 The
 137 .Fa flags
 138 argument
 139 is either
 140 .Dv DBM_INSERT
 141 or
 142 .Dv DBM_REPLACE .
 143 If
 144 .Fa flags
 145 is
 146 .Dv DBM_INSERT
 147 and the database already contains an entry for
 148 .Fa key ,
 149 that entry is not replaced.
 150 Otherwise the entry is replaced or inserted.
 151 The
 152 .Fn dbm_store
 153 function
 154 normally returns zero but returns 1 if the entry could not be
 155 inserted (because
 156 .Fa flags
 157 is
 158 .Dv DBM_INSERT ,
 159 and an entry with
 160 .Fa key
 161 already exists) or returns -1 and sets
 162 .Va errno
 163 if there were any errors.
 164 .Pp
 165 The
 166 .Fn dbm_fetch db key
 167 function
 168 returns
 169 .Dv NULL
 170 or the
 171 .Fa data
 172 corresponding to
 173 .Fa key .
 174 .Pp
 175 The
 176 .Fn dbm_delete db key
 177 function
 178 deletes the entry for
 179 .Fa key .
 180 The
 181 .Fn dbm_delete
 182 function
 183 normally returns zero but returns 1 if there was no entry with
 184 .Fa key
 185 in the database or returns -1 and sets
 186 .Va errno
 187 if there were any errors.
 188 .Pp
 189 The
 190 .Fn dbm_firstkey db
 191 function
 192 returns the first key in the database.
 193 The
 194 .Fn dbm_nextkey db
 195 function
 196 returns subsequent keys.
 197 The
 198 .Fn db_firstkey
 199 function
 200 must be called before
 201 .Fn dbm_nextkey .
 202 The order in which keys are returned is unspecified and may appear
 203 random.
 204 The
 205 .Fn dbm_nextkey
 206 function
 207 returns
 208 .Dv NULL
 209 after all keys have been returned.
 210 .Pp
 211 The
 212 .Fn dbm_error db
 213 function
 214 returns the
 215 .Va errno
 216 value of the most recent error.
 217 The
 218 .Fn dbm_clearerr db
 219 function
 220 resets this value to 0 and returns 0.
 221 .Pp
 222 The
 223 .Fn dbm_dirfno db
 224 function
 225 returns the file descriptor to the database.
 226 .Sh SEE ALSO
 227 .Xr open 2 ,
 228 .Xr dbopen 3 ,
 229 .Xr hash 3
 230 .Sh STANDARDS
 231 These functions (except
 232 .Fn dbm_dirfno )
 233 are included in the
 234 .St -susv2 .