man3/dbopen.3

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