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