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