1.\" $OpenBSD: dbopen.3,v 1.21 2003/07/07 14:43:18 jmc Exp $ 2.\" $NetBSD: dbopen.3,v 1.6 1995/02/27 13:23:25 cgd Exp $ 3.\" 4.\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. 5.\" 6.\" Copyright (c) 1990, 1993 7.\" The Regents of the University of California. All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 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.Fd #include <sys/types.h> 43.Fd #include <fcntl.h> 44.Fd #include <limits.h> 45.Fd #include <db.h> 46.Ft DB * 47.Fn dbopen "const char *file" "int flags" "int mode" "DBTYPE type" "const void *openinfo" 48.Sh DESCRIPTION 49The 50.Fn dbopen 51function is the library interface to database files. 52The supported file formats are btree, hashed, and UNIX file oriented. 53The btree format is a representation of a sorted, balanced tree structure. 54The hashed format is an extensible, dynamic hashing scheme. 55The flat-file format is a byte stream file with fixed or variable length 56records. 57The formats and file format specific information are described in detail 58in their respective manual pages 59.Xr btree 3 , 60.Xr hash 3 , 61and 62.Xr recno 3 . 63.Pp 64.Fn dbopen 65opens 66.Fa file 67for reading and/or writing. 68Files never intended to be preserved on disk may be created by setting 69the file parameter 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 , 81.Dv O_EXCL , 82.Dv O_EXLOCK , 83.Dv O_NONBLOCK , 84.Dv O_RDONLY , 85.Dv O_RDWR , 86.Dv O_SHLOCK , 87and 88.Dv O_TRUNC 89flags are meaningful. 90(Note, opening a database file 91.Dv O_WRONLY 92is not possible.) 93.\"Three additional options may be specified by 94.\".IR or 'ing 95.\"them into the 96.\".I flags 97.\"argument. 98.\".Bl -tag -width XXXXX 99.\".It 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 DB_SHMEM 105.\"Place the underlying memory pool used by the database in shared 106.\"memory. 107.\"Necessary for concurrent access. 108.\".It DB_TXN 109.\"Support transactions in the database. 110.\"The DB_LOCK and DB_SHMEM flags must be set as well. 111.\".El 112.Pp 113The 114.Fa type 115argument is of type 116.Fa DBTYPE 117(as defined in the 118.Aq Pa db.h 119include file) and may be set to 120.Dv DB_BTREE , 121.Dv 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 136.Fn dbopen 137returns a pointer to a DB structure on success and 138.Dv NULL 139on error. 140The DB structure is defined in the 141.Aq Pa db.h 142include file, and contains at least the following fields: 143.Bd -literal 144typedef struct { 145 DBTYPE type; 146 int (*close)(const DB *db); 147 int (*del)(const DB *db, const DBT *key, u_int flags); 148 int (*fd)(const DB *db); 149 int (*get)(const DB *db, DBT *key, DBT *data, u_int flags); 150 int (*put)(const DB *db, DBT *key, const DBT *data, u_int flags); 151 int (*sync)(const DB *db, u_int flags); 152 int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); 153} DB; 154.Ed 155.Pp 156These elements describe a database type and a set of functions performing 157various actions. 158These functions take a pointer to a structure as returned by 159.Fn dbopen dbopen , 160and sometimes one or more pointers to key/data structures and a flag value. 161.Bl -tag -width XXXXX -offset indent 162.It Fa type 163The type of the underlying access method (and file format). 164.It Fa close 165A pointer to a routine to flush any cached information to disk, free any 166allocated resources, and close the underlying file(s). 167Since key/data pairs may be cached in memory, failing to sync the file 168with a 169.Fa close 170or 171.Fa sync 172function may result in inconsistent or lost information. 173.Fa close 174routines return \-1 on error (setting 175.Va errno ) 176and 0 on success. 177.It Fa del 178A pointer to a routine to remove key/data pairs from the database. 179.Pp 180The parameter 181.Fa flag 182may be set to the following value: 183.Bl -tag -width XXXXX 184.It Dv R_CURSOR 185Delete the record referenced by the cursor. 186The cursor must have previously been initialized. 187.El 188.Pp 189.Fa delete 190routines return \-1 on error (setting 191.Va errno ) , 1920 on success, and 1 if the specified 193.Fa key 194was not in the file. 195.It Fa fd 196A pointer to a routine which returns a file descriptor representative 197of the underlying database. 198A file descriptor referencing the same file will be returned to all 199processes which call 200.Fn dbopen 201with the same 202.Fa file 203name. 204This file descriptor may be safely used as an argument to the 205.Xr fcntl 2 206and 207.Xr flock 2 208locking functions. 209The file descriptor is not necessarily associated with any of the 210underlying files used by the access method. 211No file descriptor is available for in memory databases. 212.Fa fd 213routines return \-1 on error (setting 214.Va errno ) , 215and the file descriptor on success. 216.It Fa get 217A pointer to a routine which is the interface for keyed retrieval from 218the database. 219The address and length of the data associated with the specified 220.Fa key 221are returned in the structure referenced by 222.Fa data . 223.Fa get 224routines return \-1 on error (setting 225.Va errno ) , 2260 on success, and 1 if the 227.Fa key 228was not in the file. 229.It Fa put 230A pointer to a routine to store key/data pairs in the database. 231.Pp 232The parameter 233.Fa flag 234may be set to one of the following values: 235.Bl -tag -width XXXXX 236.It Dv R_CURSOR 237Replace the key/data pair referenced by the cursor. 238The cursor must have previously been initialized. 239.It Dv R_IAFTER 240Append the data immediately after the data referenced by 241.Fa key , 242creating a new key/data pair. 243The record number of the appended key/data pair is returned in the 244.Fa key 245structure. 246(Applicable only to the 247.Dv DB_RECNO 248access method.) 249.It Dv R_IBEFORE 250Insert the data immediately before the data referenced by 251.Fa key , 252creating a new key/data pair. 253The record number of the inserted 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_NOOVERWRITE 260Enter the new key/data pair only if the key does not previously exist. 261.It Dv R_SETCURSOR 262Store the key/data pair, setting or initializing the position of the 263cursor to reference it. 264(Applicable only to the 265.Dv DB_BTREE 266and 267.Dv DB_RECNO 268access methods.) 269.El 270.Pp 271.Dv R_SETCURSOR 272is available only for the 273.Dv DB_BTREE 274and 275.Dv DB_RECNO 276access methods because it implies that the keys have an inherent order 277which does not change. 278.Pp 279.Dv R_IAFTER 280and 281.Dv R_IBEFORE 282are available only for the 283.Dv DB_RECNO 284access method because they each imply that the access method is able to 285create new keys. 286This is only true if the keys are ordered and independent, record numbers 287for example. 288.Pp 289The default behavior of the 290.Fa put 291routines is to enter the new key/data pair, replacing any previously 292existing key. 293.Pp 294.Fa put 295routines return \-1 on error (setting 296.Va errno ) , 2970 on success, and 1 if the 298.Dv R_NOOVERWRITE 299.Fa flag 300was set and the key already exists in the file. 301.It Fa seq 302A pointer to a routine which is the interface for sequential 303retrieval from the database. 304The address and length of the key are returned in the structure 305referenced by 306.Fa key , 307and the address and length of the data are returned in the 308structure referenced 309by 310.Fa data . 311.Pp 312Sequential key/data pair retrieval may begin at any time, and the 313position of the 314.Dq cursor 315is not affected by calls to the 316.Fa del , 317.Fa get , 318.Fa put , 319or 320.Fa sync 321routines. 322Modifications to the database during a sequential scan will be reflected 323in the scan, i.e., records inserted behind the cursor will not be returned 324while records inserted in front of the cursor will be returned. 325.Pp 326The flag value 327.Sy must 328be set to one of the following values: 329.Bl -tag -width XXXXX 330.It Dv R_CURSOR 331The data associated with the specified key is returned. 332This differs from the 333.Fa get 334routines in that it sets or initializes the cursor to the location of 335the key as well. 336(Note, for the 337.Dv DB_BTREE 338access method, the returned key is not necessarily an 339exact match for the specified key. 340The returned key is the smallest key greater than or equal to the specified 341key, permitting partial key matches and range searches.) 342.It Dv R_FIRST 343The first key/data pair of the database is returned, and the cursor 344is set or initialized to reference it. 345.It Dv R_LAST 346The last key/data pair of the database is returned, and the cursor 347is set or initialized to reference it. 348(Applicable only to the 349.Dv DB_BTREE 350and 351.Dv DB_RECNO 352access methods.) 353.It Dv R_NEXT 354Retrieve the key/data pair immediately after the cursor. 355If the cursor is not yet set, this is the same as the 356.Dv R_FIRST 357flag. 358.It Dv R_PREV 359Retrieve the key/data pair immediately before the cursor. 360If the cursor is not yet set, this is the same as the 361.Dv R_LAST 362flag. 363(Applicable only to the 364.Dv DB_BTREE 365and 366.Dv DB_RECNO 367access methods.) 368.El 369.Pp 370.Dv R_LAST 371and 372.Dv R_PREV 373are available only for the 374.Dv DB_BTREE 375and 376.Dv DB_RECNO 377access methods because they each imply that the keys have an inherent 378order which does not change. 379.Pp 380.Fa seq 381routines return \-1 on error (setting 382.Va errno ) , 3830 on success and 1 if there are no key/data pairs less than or greater 384than the specified or current key. 385If the 386.Dv DB_RECNO 387access method is being used, and if the database file 388is a character special file and no complete key/data pairs are currently 389available, the 390.Fa seq 391routines return 2. 392.It Fa sync 393A pointer to a routine to flush any cached information to disk. 394If the database is in memory only, the 395.Fa sync 396routine has no effect and will always succeed. 397.Pp 398The flag value may be set to the following value: 399.Bl -tag -width XXXXX 400.It Dv R_RECNOSYNC 401If the 402.Dv DB_RECNO 403access method is being used, this flag causes 404the sync routine to apply to the btree file which underlies the 405recno file, not the recno file itself. 406(See the 407.Fa bfname 408field of the 409.Xr recno 3 410manual page for more information.) 411.El 412.Pp 413.Fa sync 414routines return \-1 on error (setting 415.Va errno ) 416and 0 on success. 417.El 418.Sh KEY/DATA PAIRS 419Access to all file types is based on key/data pairs. 420Both keys and data are represented by the following data structure: 421.Pp 422.Bl -item -compact 423.It 424typedef struct { 425.It 426.Bl -item -compact -offset indent 427.It 428void *data; 429.It 430size_t size; 431.El 432.It 433} DBT; 434.El 435.Pp 436The elements of the DBT structure are defined as follows: 437.Bl -tag -width XXXXX 438.It Fa data 439A pointer to a byte string. 440.It Fa size 441The length of the byte string. 442.El 443.Pp 444Key and data byte strings may reference strings of essentially unlimited 445length although any two of them must fit into available memory at the same 446time. 447It should be noted that the access methods provide no guarantees about 448byte string alignment. 449.Sh ERRORS 450The 451.Fn dbopen 452routine may fail and set 453.Va errno 454for any of the errors specified for the library routines 455.Xr open 2 456and 457.Xr malloc 3 458or the following: 459.Bl -tag -width XEINVALX 460.It Bq Er EFTYPE 461A file is incorrectly formatted. 462.It Bq Er EINVAL 463A parameter has been specified (hash function, pad byte etc.) that is 464incompatible with the current file specification or which is not 465meaningful for the function (for example, use of the cursor without 466prior initialization) or there is a mismatch between the version 467number of file and the software. 468.El 469.Pp 470The 471.Fa close 472routines may fail and set 473.Va errno 474for any of the errors specified for the library routines 475.Xr close 2 , 476.Xr read 2 , 477.Xr write 2 , 478.Xr free 3 , 479or 480.Xr fsync 2 . 481.Pp 482The 483.Fa del , 484.Fa get , 485.Fa put , 486and 487.Fa seq 488routines may fail and set 489.Va errno 490for any of the errors specified for the library routines 491.Xr read 2 , 492.Xr write 2 , 493.Xr free 3 , 494or 495.Xr malloc 3 . 496.Pp 497The 498.Fa fd 499routines will fail and set 500.Va errno 501to 502.Er ENOENT 503for in memory databases. 504.Pp 505The 506.Fa sync 507routines may fail and set 508.Va errno 509for any of the errors specified for the library routine 510.Xr fsync 2 . 511.Sh SEE ALSO 512.Xr btree 3 , 513.Xr hash 3 , 514.Xr mpool 3 , 515.Xr recno 3 516.Rs 517.%T "LIBTP: Portable, Modular Transactions for UNIX" 518.%A Margo Seltzer 519.%A Michael Olson 520.%J USENIX proceedings 521.%D Winter 1992 522.Re 523.Sh BUGS 524The typedef DBT is a mnemonic for 525.Dq data base thang , 526and was used 527because no one could think of a reasonable name that wasn't already used. 528.Pp 529The file descriptor interface is a kludge and will be deleted in a 530future version of the interface. 531.Pp 532None of the access methods provide any form of concurrent access, 533locking, or transactions. 534