man3/dbopen.3

   1 .\" Copyright (c) 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)dbopen.3    8.5 (Berkeley) 1/2/94
  33 .\"
  34 .TH DBOPEN 3 1994-01-02 "" "Linux Programmer's Manual"
  35 .UC 7
  36 .SH NAME
  37 dbopen \- database access methods
  38 .SH SYNOPSIS
  39 .nf
  40 .B #include <sys/types.h>
  41 .B #include <limits.h>
  42 .B #include <db.h>
  43
  44 .BI "DB *dbopen(const char *" file ", int " flags ", int " mode \
  45 ", DBTYPE " type ,
  46 .BI "           const void *" openinfo );
  47 .fi
  48 .SH DESCRIPTION
  49 .BR dbopen ()
  50 is the library interface to database files.
  51 The supported file formats are btree, hashed and UNIX file oriented.
  52 The btree format is a representation of a sorted, balanced tree structure.
  53 The hashed format is an extensible, dynamic hashing scheme.
  54 The flat-file format is a byte stream file with fixed or variable length
  55 records.
  56 The formats and file format specific information are described in detail
  57 in their respective manual pages
  58 .BR btree (3),
  59 .BR hash (3)
  60 and
  61 .BR recno (3).
  62 .PP
  63 .BR dbopen ()
  64 opens
  65 .I file
  66 for reading and/or writing.
  67 Files never intended to be preserved on disk may be created by setting
  68 the file parameter to NULL.
  69 .PP
  70 The
  71 .I flags
  72 and
  73 .I mode
  74 arguments are as specified to the
  75 .BR open (2)
  76 routine, however, only the
  77 .BR O_CREAT ,
  78 .BR O_EXCL ,
  79 .BR O_EXLOCK ,
  80 .BR O_NONBLOCK ,
  81 .BR O_RDONLY ,
  82 .BR O_RDWR ,
  83 .BR O_SHLOCK ,
  84 and
  85 .B O_TRUNC
  86 flags are meaningful.
  87 (Note, opening a database file
  88 .B O_WRONLY
  89 is not possible.)
  90 .\"Three additional options may be specified by
  91 .\".IR or 'ing
  92 .\"them into the
  93 .\".I flags
  94 .\"argument.
  95 .\".TP
  96 .\"DB_LOCK
  97 .\"Do the necessary locking in the database to support concurrent access.
  98 .\"If concurrent access isn't needed or the database is read-only this
  99 .\"flag should not be set, as it tends to have an associated performance
 100 .\"penalty.
 101 .\".TP
 102 .\"DB_SHMEM
 103 .\"Place the underlying memory pool used by the database in shared
 104 .\"memory.
 105 .\"Necessary for concurrent access.
 106 .\".TP
 107 .\"DB_TXN
 108 .\"Support transactions in the database.
 109 .\"The DB_LOCK and DB_SHMEM flags must be set as well.
 110 .PP
 111 The
 112 .I type
 113 argument is of type
 114 .I DBTYPE
 115 (as defined in the
 116 .I <db.h>
 117 include file) and
 118 may be set to
 119 .BR DB_BTREE ,
 120 .BR DB_HASH ,
 121 or
 122 .BR DB_RECNO .
 123 .PP
 124 The
 125 .I openinfo
 126 argument is a pointer to an access method specific structure described
 127 in the access method's manual page.
 128 If
 129 .I openinfo
 130 is NULL, each access method will use defaults appropriate for the system
 131 and the access method.
 132 .PP
 133 .BR dbopen ()
 134 returns a pointer to a
 135 .I DB
 136 structure on success and NULL on error.
 137 The
 138 .I DB
 139 structure is defined in the
 140 .I <db.h>
 141 include file, and contains at
 142 least the following fields:
 143 .sp
 144 .in +0.5i
 145 .nf
 146 typedef struct {
 147     DBTYPE type;
 148     int (*close)(const DB *db);
 149     int (*del)(const DB *db, const DBT *key, u_int flags);
 150     int (*fd)(const DB *db);
 151     int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
 152     int (*put)(const DB *db, DBT *key, const DBT *data,
 153                u_int flags);
 154     int (*sync)(const DB *db, u_int flags);
 155     int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
 156 } DB;
 157 .fi
 158 .in
 159 .PP
 160 These elements describe a database type and a set of functions performing
 161 various actions.
 162 These functions take a pointer to a structure as returned by
 163 .BR dbopen (),
 164 and sometimes one or more pointers to key/data structures and a flag value.
 165 .TP
 166 type
 167 The type of the underlying access method (and file format).
 168 .TP
 169 close
 170 A pointer to a routine to flush any cached information to disk, free any
 171 allocated resources, and close the underlying file(s).
 172 Since key/data pairs may be cached in memory, failing to sync the file
 173 with a
 174 .I close
 175 or
 176 .I sync
 177 function may result in inconsistent or lost information.
 178 .I Close
 179 routines return \-1 on error (setting
 180 .IR errno )
 181 and 0 on success.
 182 .TP
 183 del
 184 A pointer to a routine to remove key/data pairs from the database.
 185 .IP
 186 The parameter
 187 .I flag
 188 may be set to the following value:
 189 .RS
 190 .TP
 191 .B R_CURSOR
 192 Delete the record referenced by the cursor.
 193 The cursor must have previously been initialized.
 194 .RE
 195 .IP
 196 .I Delete
 197 routines return \-1 on error (setting
 198 .IR errno ),
 199 0 on success, and 1 if the specified
 200 .I key
 201 was not in the file.
 202 .TP
 203 fd
 204 A pointer to a routine which returns a file descriptor representative
 205 of the underlying database.
 206 A file descriptor referencing the same file will be returned to all
 207 processes which call
 208 .BR dbopen ()
 209 with the same
 210 .I file
 211 name.
 212 This file descriptor may be safely used as an argument to the
 213 .BR fcntl (2)
 214 and
 215 .BR flock (2)
 216 locking functions.
 217 The file descriptor is not necessarily associated with any of the
 218 underlying files used by the access method.
 219 No file descriptor is available for in memory databases.
 220 .I Fd
 221 routines return \-1 on error (setting
 222 .IR errno ),
 223 and the file descriptor on success.
 224 .TP
 225 get
 226 A pointer to a routine which is the interface for keyed retrieval from
 227 the database.
 228 The address and length of the data associated with the specified
 229 .I key
 230 are returned in the structure referenced by
 231 .IR data .
 232 .I Get
 233 routines return \-1 on error (setting
 234 .IR errno ),
 235 0 on success, and 1 if the
 236 .I key
 237 was not in the file.
 238 .TP
 239 put
 240 A pointer to a routine to store key/data pairs in the database.
 241 .IP
 242 The parameter
 243 .I flag
 244 may be set to one of the following values:
 245 .RS
 246 .TP
 247 .B R_CURSOR
 248 Replace the key/data pair referenced by the cursor.
 249 The cursor must have previously been initialized.
 250 .TP
 251 .B R_IAFTER
 252 Append the data immediately after the data referenced by
 253 .IR key ,
 254 creating a new key/data pair.
 255 The record number of the appended key/data pair is returned in the
 256 .I key
 257 structure.
 258 (Applicable only to the
 259 .B DB_RECNO
 260 access method.)
 261 .TP
 262 .B R_IBEFORE
 263 Insert the data immediately before the data referenced by
 264 .IR key ,
 265 creating a new key/data pair.
 266 The record number of the inserted key/data pair is returned in the
 267 .I key
 268 structure.
 269 (Applicable only to the
 270 .B DB_RECNO
 271 access method.)
 272 .TP
 273 .B R_NOOVERWRITE
 274 Enter the new key/data pair only if the key does not previously exist.
 275 .TP
 276 .B R_SETCURSOR
 277 Store the key/data pair, setting or initializing the position of the
 278 cursor to reference it.
 279 (Applicable only to the
 280 .B DB_BTREE
 281 and
 282 .B DB_RECNO
 283 access methods.)
 284 .RE
 285 .IP
 286 .B R_SETCURSOR
 287 is available only for the
 288 .B DB_BTREE
 289 and
 290 .B DB_RECNO
 291 access
 292 methods because it implies that the keys have an inherent order
 293 which does not change.
 294 .IP
 295 .B R_IAFTER
 296 and
 297 .B R_IBEFORE
 298 are available only for the
 299 .B DB_RECNO
 300 access method because they each imply that the access method is able to
 301 create new keys.
 302 This is only true if the keys are ordered and independent, record numbers
 303 for example.
 304 .IP
 305 The default behavior of the
 306 .I put
 307 routines is to enter the new key/data pair, replacing any previously
 308 existing key.
 309 .IP
 310 .I Put
 311 routines return \-1 on error (setting
 312 .IR errno ),
 313 0 on success, and 1 if the
 314 .B R_NOOVERWRITE
 315 .I flag
 316 was set and the key already exists in the file.
 317 .TP
 318 seq
 319 A pointer to a routine which is the interface for sequential
 320 retrieval from the database.
 321 The address and length of the key are returned in the structure
 322 referenced by
 323 .IR key ,
 324 and the address and length of the data are returned in the
 325 structure referenced
 326 by
 327 .IR data .
 328 .IP
 329 Sequential key/data pair retrieval may begin at any time, and the
 330 position of the ``cursor'' is not affected by calls to the
 331 .IR del ,
 332 .IR get ,
 333 .IR put ,
 334 or
 335 .I sync
 336 routines.
 337 Modifications to the database during a sequential scan will be reflected
 338 in the scan, that is,
 339 records inserted behind the cursor will not be returned
 340 while records inserted in front of the cursor will be returned.
 341 .IP
 342 The flag value
 343 .B must
 344 be set to one of the following values:
 345 .RS
 346 .TP
 347 .B R_CURSOR
 348 The data associated with the specified key is returned.
 349 This differs from the
 350 .I get
 351 routines in that it sets or initializes the cursor to the location of
 352 the key as well.
 353 (Note, for the
 354 .B DB_BTREE
 355 access method, the returned key is not necessarily an
 356 exact match for the specified key.
 357 The returned key is the smallest key greater than or equal to the specified
 358 key, permitting partial key matches and range searches.)
 359 .TP
 360 .B R_FIRST
 361 The first key/data pair of the database is returned, and the cursor
 362 is set or initialized to reference it.
 363 .TP
 364 .B R_LAST
 365 The last key/data pair of the database is returned, and the cursor
 366 is set or initialized to reference it.
 367 (Applicable only to the
 368 .B DB_BTREE
 369 and
 370 .B DB_RECNO
 371 access methods.)
 372 .TP
 373 .B R_NEXT
 374 Retrieve the key/data pair immediately after the cursor.
 375 If the cursor is not yet set, this is the same as the
 376 .B R_FIRST
 377 flag.
 378 .TP
 379 .B R_PREV
 380 Retrieve the key/data pair immediately before the cursor.
 381 If the cursor is not yet set, this is the same as the
 382 .B R_LAST
 383 flag.
 384 (Applicable only to the
 385 .B DB_BTREE
 386 and
 387 .B DB_RECNO
 388 access methods.)
 389 .RE
 390 .IP
 391 .B R_LAST
 392 and
 393 .B R_PREV
 394 are available only for the
 395 .B DB_BTREE
 396 and
 397 .B DB_RECNO
 398 access methods because they each imply that the keys have an inherent
 399 order which does not change.
 400 .IP
 401 .I Seq
 402 routines return \-1 on error (setting
 403 .IR errno ),
 404 0 on success and 1 if there are no key/data pairs less than or greater
 405 than the specified or current key.
 406 If the
 407 .B DB_RECNO
 408 access method is being used, and if the database file
 409 is a character special file and no complete key/data pairs are currently
 410 available, the
 411 .I seq
 412 routines return 2.
 413 .TP
 414 sync
 415 A pointer to a routine to flush any cached information to disk.
 416 If the database is in memory only, the
 417 .I sync
 418 routine has no effect and will always succeed.
 419 .IP
 420 The flag value may be set to the following value:
 421 .RS
 422 .TP
 423 .B R_RECNOSYNC
 424 If the
 425 .B DB_RECNO
 426 access method is being used, this flag causes
 427 the sync routine to apply to the btree file which underlies the
 428 recno file, not the recno file itself.
 429 (See the
 430 .I bfname
 431 field of the
 432 .BR recno (3)
 433 manual page for more information.)
 434 .RE
 435 .IP
 436 .I Sync
 437 routines return \-1 on error (setting
 438 .IR errno )
 439 and 0 on success.
 440 .SS "Key/Data Pairs"
 441 Access to all file types is based on key/data pairs.
 442 Both keys and data are represented by the following data structure:
 443 .in +0.5i
 444 .nf
 445
 446 typedef struct {
 447     void  *data;
 448     size_t size;
 449 } DBT;
 450 .fi
 451 .in
 452 .PP
 453 The elements of the
 454 .I DBT
 455 structure are defined as follows:
 456 .TP
 457 data
 458 A pointer to a byte string.
 459 .TP
 460 size
 461 The length of the byte string.
 462 .PP
 463 Key and data byte strings may reference strings of essentially unlimited
 464 length although any two of them must fit into available memory at the same
 465 time.
 466 It should be noted that the access methods provide no guarantees about
 467 byte string alignment.
 468 .SH ERRORS
 469 The
 470 .BR dbopen ()
 471 routine may fail and set
 472 .I errno
 473 for any of the errors specified for the library routines
 474 .BR open (2)
 475 and
 476 .BR malloc (3)
 477 or the following:
 478 .TP
 479 .B EFTYPE
 480 A file is incorrectly formatted.
 481 .TP
 482 .B EINVAL
 483 A parameter has been specified (hash function, pad byte etc.) that is
 484 incompatible with the current file specification or which is not
 485 meaningful for the function (for example, use of the cursor without
 486 prior initialization) or there is a mismatch between the version
 487 number of file and the software.
 488 .PP
 489 The
 490 .I close
 491 routines may fail and set
 492 .I errno
 493 for any of the errors specified for the library routines
 494 .BR close (2),
 495 .BR read (2),
 496 .BR write (2),
 497 .BR free (3),
 498 or
 499 .BR fsync (2).
 500 .PP
 501 The
 502 .IR del ,
 503 .IR get ,
 504 .I put
 505 and
 506 .I seq
 507 routines may fail and set
 508 .I errno
 509 for any of the errors specified for the library routines
 510 .BR read (2),
 511 .BR write (2),
 512 .BR free (3)
 513 or
 514 .BR malloc (3).
 515 .PP
 516 The
 517 .I fd
 518 routines will fail and set
 519 .I errno
 520 to
 521 .B ENOENT
 522 for in memory databases.
 523 .PP
 524 The
 525 .I sync
 526 routines may fail and set
 527 .I errno
 528 for any of the errors specified for the library routine
 529 .BR fsync (2).
 530 .SH BUGS
 531 The typedef
 532 .I DBT
 533 is a mnemonic for ``data base thang'', and was used
 534 because no-one could think of a reasonable name that wasn't already used.
 535 .PP
 536 The file descriptor interface is a kludge and will be deleted in a
 537 future version of the interface.
 538 .PP
 539 None of the access methods provide any form of concurrent access,
 540 locking, or transactions.
 541 .SH "SEE ALSO"
 542 .BR btree (3),
 543 .BR hash (3),
 544 .BR mpool (3),
 545 .BR recno (3)
 546 .sp
 547 .IR "LIBTP: Portable, Modular Transactions for UNIX" ,
 548 Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.