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