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