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