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.5 2001/10/01 16:08:50 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 .Aq Pa ndbm.h :
  69 .Bd -literal
  70 typedef struct {
  71         char *dptr;
  72         int dsize;
  73 } datum;
  74 .Ed
  75 .Pp
  76 .Fn dbm_open base flags mode
  77 opens or creates a database.
  78 .Fa base
  79 is the basename of the file containing
  80 the database; the actual database has a
  81 .Pa .db
  82 suffix.
  83 I.e., if
  84 .Fa base
  85 is
  86 .Qq Li /home/me/mystuff
  87 then the actual database is in the file
  88 .Pa /home/me/mystuff.db .
  89 .Fa flags
  90 and
  91 .Fa mode
  92 are passed to
  93 .Xr open 2 .
  94 .Pq Dv O_RDWR | O_CREAT
  95 is a typical value for
  96 .Fa flags ;
  97 .Li 0660
  98 is a typical value for
  99 .Fa mode .
 100 .Dv O_WRONLY
 101 is not allowed in
 102 .Fa flags .
 103 The pointer returned by
 104 .Fn dbm_open
 105 identifies the database and is the
 106 .Fa db
 107 argument to the other functions.
 108 .Fn dbm_open
 109 returns
 110 .Dv NULL
 111 and sets
 112 .Va errno
 113 if there were any errors.
 114 .Pp
 115 .Fn dbm_close db
 116 closes the database.
 117 .Fn dbm_close
 118 normally returns zero.
 119 .Pp
 120 .Fn dbm_store db key data flags
 121 inserts or replaces an entry in the database.
 122 .Fa flags
 123 is either
 124 .Dv DBM_INSERT
 125 or
 126 .Dv DBM_REPLACE .
 127 If
 128 .Fa flags
 129 is
 130 .Dv DBM_INSERT
 131 and the database already contains an entry for
 132 .Fa key ,
 133 that entry is not replaced.
 134 Otherwise the entry is replaced or inserted.
 135 .Fn dbm_store
 136 normally returns zero but returns 1 if the entry could not be
 137 inserted (because
 138 .Fa flags
 139 is
 140 .Dv DBM_INSERT ,
 141 and an entry with
 142 .Fa key
 143 already exists) or returns -1 and sets
 144 .Va errno
 145 if there were any errors.
 146 .Pp
 147 .Fn dbm_fetch db key
 148 returns
 149 .Dv NULL
 150 or the
 151 .Fa data
 152 corresponding to
 153 .Fa key .
 154 .Pp
 155 .Fn dbm_delete db key
 156 deletes the entry for
 157 .Fa key .
 158 .Fn dbm_delete
 159 normally returns zero but returns 1 if there was no entry with
 160 .Fa key
 161 in the database or returns -1 and sets
 162 .Va errno
 163 if there were any errors.
 164 .Pp
 165 .Fn dbm_firstkey db
 166 returns the first key in the database.
 167 .Fn dbm_nextkey db
 168 returns subsequent keys.
 169 .Fn db_firstkey
 170 must be called before
 171 .Fn dbm_nextkey .
 172 The order in which keys are returned is unspecified and may appear
 173 random.
 174 .Fn dbm_nextkey
 175 returns
 176 .Dv NULL
 177 after all keys have been returned.
 178 .Pp
 179 .Fn dbm_error db
 180 returns the
 181 .Va errno
 182 value of the most recent error.
 183 .Fn dbm_clearerr db
 184 resets this value to 0 and returns 0.
 185 .Pp
 186 .Fn dbm_dirfno db
 187 returns the file descriptor to the database.
 188 .Sh SEE ALSO
 189 .Xr open 2 ,
 190 .Xr dbopen 3 ,
 191 .Xr hash 3
 192 .Sh STANDARDS
 193 These functions (except
 194 .Fn dbm_dirfno )
 195 are included in the
 196 .St -susv2 .