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