ext/SDBM_File/sdbm.3

   1 .\" $Id: sdbm.3,v 1.2 90/12/13 13:00:57 oz Exp $
   2 .TH SDBM 3 "1 March 1990"
   3 .SH NAME
   4 sdbm, sdbm_open, sdbm_prep, sdbm_close, sdbm_fetch, sdbm_store, sdbm_delete, sdbm_exists, sdbm_firstkey, sdbm_nextkey, sdbm_hash, sdbm_rdonly, sdbm_error, sdbm_clearerr, sdbm_dirfno, sdbm_pagfno \- data base subroutines
   5 .SH SYNOPSIS
   6 .nf
   7 .ft B
   8 #include <sdbm.h>
   9 .sp
  10 typedef struct {
  11         char *dptr;
  12         int dsize;
  13 } datum;
  14 .sp
  15 datum nullitem = { NULL, 0 };
  16 .sp
  17 \s-1DBM\s0 *sdbm_open(char *file, int flags, int mode)
  18 .sp
  19 \s-1DBM\s0 *sdbm_prep(char *dirname, char *pagname, int flags, int mode)
  20 .sp
  21 void sdbm_close(\s-1DBM\s0 *db)
  22 .sp
  23 datum sdbm_fetch(\s-1DBM\s0 *db, key)
  24 .sp
  25 int sdbm_store(\s-1DBM\s0 *db, datum key, datum val, int flags)
  26 .sp
  27 int sdbm_delete(\s-1DBM\s0 *db, datum key)
  28 .sp
  29 int sdbm_exists(\s-1DBM\s0 *db, datum key)
  30 .sp
  31 datum sdbm_firstkey(\s-1DBM\s0 *db)
  32 .sp
  33 datum sdbm_nextkey(\s-1DBM\s0 *db)
  34 .sp
  35 long sdbm_hash(char *string, int len)
  36 .sp
  37 int sdbm_rdonly(\s-1DBM\s0 *db)
  38 int sdbm_error(\s-1DBM\s0 *db)
  39 sdbm_clearerr(\s-1DBM\s0 *db)
  40 int sdbm_dirfno(\s-1DBM\s0 *db)
  41 int sdbm_pagfno(\s-1DBM\s0 *db)
  42 .ft R
  43 .fi
  44 .SH DESCRIPTION
  45 .IX "database library" sdbm "" "\fLsdbm\fR"
  46 .IX sdbm_open "" "\fLsdbm_open\fR \(em open \fLsdbm\fR database"
  47 .IX sdbm_prep "" "\fLsdbm_prep\fR \(em prepare \fLsdbm\fR database"
  48 .IX sdbm_close "" "\fLsdbm_close\fR \(em close \fLsdbm\fR routine"
  49 .IX sdbm_fetch "" "\fLsdbm_fetch\fR \(em fetch \fLsdbm\fR database data"
  50 .IX sdbm_store "" "\fLsdbm_store\fR \(em add data to \fLsdbm\fR database"
  51 .IX sdbm_delete "" "\fLsdbm_delete\fR \(em remove data from \fLsdbm\fR database"
  52 .IX sdbm_exists "" "\fLsdbm_exists\fR \(em test \fLsdbm\fR key existence"
  53 .IX sdbm_firstkey "" "\fLsdbm_firstkey\fR \(em access \fLsdbm\fR database"
  54 .IX sdbm_nextkey "" "\fLsdbm_nextkey\fR \(em access \fLsdbm\fR database"
  55 .IX sdbm_hash "" "\fLsdbm_hash\fR \(em string hash for \fLsdbm\fR database"
  56 .IX sdbm_rdonly "" "\fLsdbm_rdonly\fR \(em return \fLsdbm\fR database read-only mode"
  57 .IX sdbm_error "" "\fLsdbm_error\fR \(em return \fLsdbm\fR database error condition"
  58 .IX sdbm_clearerr "" "\fLsdbm_clearerr\fR \(em clear \fLsdbm\fR database error condition"
  59 .IX sdbm_dirfno "" "\fLsdbm_dirfno\fR \(em return \fLsdbm\fR database bitmap file descriptor"
  60 .IX sdbm_pagfno "" "\fLsdbm_pagfno\fR \(em return \fLsdbm\fR database data file descriptor"
  61 .IX "database functions \(em \fLsdbm\fR"  sdbm_open  ""  \fLsdbm_open\fP
  62 .IX "database functions \(em \fLsdbm\fR"  sdbm_prep  ""  \fLsdbm_prep\fP
  63 .IX "database functions \(em \fLsdbm\fR"  sdbm_close  ""  \fLsdbm_close\fP
  64 .IX "database functions \(em \fLsdbm\fR"  sdbm_fetch  ""  \fLsdbm_fetch\fP
  65 .IX "database functions \(em \fLsdbm\fR"  sdbm_store  ""  \fLsdbm_store\fP
  66 .IX "database functions \(em \fLsdbm\fR"  sdbm_delete  ""  \fLsdbm_delete\fP
  67 .IX "database functions \(em \fLsdbm\fR"  sdbm_firstkey  ""  \fLsdbm_firstkey\fP
  68 .IX "database functions \(em \fLsdbm\fR"  sdbm_nextkey  ""  \fLsdbm_nextkey\fP
  69 .IX "database functions \(em \fLsdbm\fR"  sdbm_rdonly  ""  \fLsdbm_rdonly\fP
  70 .IX "database functions \(em \fLsdbm\fR"  sdbm_error  ""  \fLsdbm_error\fP
  71 .IX "database functions \(em \fLsdbm\fR"  sdbm_clearerr  ""  \fLsdbm_clearerr\fP
  72 .IX "database functions \(em \fLsdbm\fR"  sdbm_dirfno  ""  \fLsdbm_dirfno\fP
  73 .IX "database functions \(em \fLsdbm\fR"  sdbm_pagfno  ""  \fLsdbm_pagfno\fP
  74 .LP
  75 This package allows an application to maintain a mapping of <key,value> pairs
  76 in disk files.  This is not to be considered a real database system, but is
  77 still useful in many simple applications built around fast retrieval of a data
  78 value from a key.  This implementation uses an external hashing scheme,
  79 called Dynamic Hashing, as described by Per-Aake Larson in BIT 18 (1978) pp.
  80 184-201.  Retrieval of any item usually requires a single disk access.
  81 The application interface is compatible with the
  82 .IR ndbm (3)
  83 library.
  84 .LP
  85 An
  86 .B sdbm
  87 database is kept in two files usually given the extensions
  88 .B \.dir
  89 and
  90 .BR \.pag .
  91 The
  92 .B \.dir
  93 file contains a bitmap representing a forest of binary hash trees, the leaves
  94 of which indicate data pages in the
  95 .B \.pag
  96 file.
  97 .LP
  98 The application interface uses the
  99 .B datum
 100 structure to describe both
 101 .I keys
 102 and
 103 .IR value s.
 104 A
 105 .B datum
 106 specifies a byte sequence of
 107 .I dsize
 108 size pointed to by
 109 .IR dptr .
 110 If you use
 111 .SM ASCII
 112 strings as
 113 .IR key s
 114 or
 115 .IR value s,
 116 then you must decide whether or not to include the terminating
 117 .SM NUL
 118 byte which sometimes defines strings.  Including it will require larger
 119 database files, but it will be possible to get sensible output from a
 120 .IR strings (1)
 121 command applied to the data file.
 122 .LP
 123 In order to allow a process using this package to manipulate multiple
 124 databases, the applications interface always requires a
 125 .IR handle ,
 126 a
 127 .BR "DBM *" ,
 128 to identify the database to be manipulated.  Such a handle can be obtained
 129 from the only routines that do not require it, namely
 130 .BR sdbm_open (\|)
 131 or
 132 .BR sdbm_prep (\|).
 133 Either of these will open or create the two necessary files.  The
 134 difference is that the latter allows explicitly naming the bitmap and data
 135 files whereas
 136 .BR sdbm_open (\|)
 137 will take a base file name and call
 138 .BR sdbm_prep (\|)
 139 with the default extensions.
 140 The
 141 .I flags
 142 and
 143 .I mode
 144 parameters are the same as for
 145 .BR open (2).
 146 .LP
 147 To free the resources occupied while a database handle is active, call
 148 .BR sdbm_close (\|).
 149 .LP
 150 Given a handle, one can retrieve data associated with a key by using the
 151 .BR sdbm_fetch (\|)
 152 routine, and associate data with a key by using the
 153 .BR sdbm_store (\|)
 154 routine.
 155 .BR sdbm_exists (\|)
 156 will say whether a given key exists in the database.
 157 .LP
 158 The values of the
 159 .I flags
 160 parameter for
 161 .BR sdbm_store (\|)
 162 can be either
 163 .BR \s-1DBM_INSERT\s0 ,
 164 which will not change an existing entry with the same key, or
 165 .BR \s-1DBM_REPLACE\s0 ,
 166 which will replace an existing entry with the same key.
 167 Keys are unique within the database.
 168 .LP
 169 To delete a key and its associated value use the
 170 .BR sdbm_delete (\|)
 171 routine.
 172 .LP
 173 To retrieve every key in the database, use a loop like:
 174 .sp
 175 .nf
 176 .ft B
 177 for (key = sdbm_firstkey(db); key.dptr != NULL; key = sdbm_nextkey(db))
 178         ;
 179 .ft R
 180 .fi
 181 .LP
 182 The order of retrieval is unspecified.
 183 .LP
 184 If you determine that the performance of the database is inadequate or
 185 you notice clustering or other effects that may be due to the hashing
 186 algorithm used by this package, you can override it by supplying your
 187 own
 188 .BR sdbm_hash (\|)
 189 routine.  Doing so will make the database unintelligible to any other
 190 applications that do not use your specialized hash function.
 191 .sp
 192 .LP
 193 The following macros are defined in the header file:
 194 .IP
 195 .BR sdbm_rdonly (\|)
 196 returns true if the database has been opened read\-only.
 197 .IP
 198 .BR sdbm_error (\|)
 199 returns true if an I/O error has occurred.
 200 .IP
 201 .BR sdbm_clearerr (\|)
 202 allows you to clear the error flag if you think you know what the error
 203 was and insist on ignoring it.
 204 .IP
 205 .BR sdbm_dirfno (\|)
 206 returns the file descriptor associated with the bitmap file.
 207 .IP
 208 .BR sdbm_pagfno (\|)
 209 returns the file descriptor associated with the data file.
 210 .SH SEE ALSO
 211 .IR open (2).
 212 .SH DIAGNOSTICS
 213 Functions that return a
 214 .B "DBM *"
 215 handle will use
 216 .SM NULL
 217 to indicate an error.
 218 Functions that return an
 219 .B int
 220 will use \-1 to indicate an error.  The normal return value in that case is 0.
 221 Functions that return a
 222 .B datum
 223 will return
 224 .B nullitem
 225 to indicate an error.
 226 .LP
 227 As a special case of
 228 .BR sdbm_store (\|),
 229 if it is called with the
 230 .B \s-1DBM_INSERT\s0
 231 flag and the key already exists in the database, the return value will be 1.
 232 .LP
 233 In general, if a function parameter is invalid,
 234 .B errno
 235 will be set to
 236 .BR \s-1EINVAL\s0 .
 237 If a write operation is requested on a read-only database,
 238 .B errno
 239 will be set to
 240 .BR \s-1ENOPERM\s0 .
 241 If a memory allocation (using
 242 .IR malloc (3))
 243 failed,
 244 .B errno
 245 will be set to
 246 .BR \s-1ENOMEM\s0 .
 247 For I/O operation failures
 248 .B errno
 249 will contain the value set by the relevant failed system call, either
 250 .IR read (2),
 251 .IR write (2),
 252 or
 253 .IR lseek (2).
 254 .SH AUTHOR
 255 .IP "Ozan S. Yigit" (oz@nexus.yorku.ca)
 256 .SH BUGS
 257 The sum of key and value data sizes must not exceed
 258 .B \s-1PAIRMAX\s0
 259 (1008 bytes).
 260 .LP
 261 The sum of the key and value data sizes where several keys hash to the
 262 same value must fit within one bitmap page.
 263 .LP
 264 The
 265 .B \.pag
 266 file will contain holes, so its apparent size is larger than its contents.
 267 When copied through the filesystem the holes will be filled.
 268 .LP
 269 The contents of
 270 .B datum
 271 values returned are in volatile storage.  If you want to retain the values
 272 pointed to, you must copy them immediately before another call to this package.
 273 .LP
 274 The only safe way for multiple processes to (read and) update a database at
 275 the same time, is to implement a private locking scheme outside this package
 276 and open and close the database between lock acquisitions.  It is safe for
 277 multiple processes to concurrently access a database read-only.
 278 .SH APPLICATIONS PORTABILITY
 279 For complete source code compatibility with the Berkeley Unix
 280 .IR ndbm (3)
 281 library, the
 282 .B sdbm.h
 283 header file should be installed in
 284 .BR /usr/include/ndbm.h .
 285 .LP
 286 The
 287 .B nullitem
 288 data item, and the
 289 .BR sdbm_prep (\|),
 290 .BR sdbm_hash (\|),
 291 .BR sdbm_rdonly (\|),
 292 .BR sdbm_dirfno (\|),
 293 and
 294 .BR sdbm_pagfno (\|)
 295 functions are unique to this package.