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