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