man3/dbopen.3

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