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