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$
  17 .\"
  18 .Dd February 19, 2015
  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 or returns -1 and sets
 178 .Va errno
 179 if there were any errors.
 180 .Pp
 181 The
 182 .Fn dbm_firstkey db
 183 function
 184 returns the first key in the database.
 185 The
 186 .Fn dbm_nextkey db
 187 function
 188 returns subsequent keys.
 189 The
 190 .Fn db_firstkey
 191 function
 192 must be called before
 193 .Fn dbm_nextkey .
 194 The order in which keys are returned is unspecified and may appear
 195 random.
 196 The
 197 .Fn dbm_nextkey
 198 function
 199 returns
 200 .Dv NULL
 201 after all keys have been returned.
 202 .Pp
 203 The
 204 .Fn dbm_error db
 205 function
 206 returns the
 207 .Va errno
 208 value of the most recent error.
 209 The
 210 .Fn dbm_clearerr db
 211 function
 212 resets this value to 0 and returns 0.
 213 .Pp
 214 The
 215 .Fn dbm_dirfno db
 216 function
 217 returns the file descriptor to the database.
 218 .Sh SEE ALSO
 219 .Xr open 2 ,
 220 .Xr dbopen 3 ,
 221 .Xr hash 3
 222 .Sh STANDARDS
 223 These functions (except
 224 .Fn dbm_dirfno )
 225 are included in the
 226 .St -susv2 .