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