1.\" $OpenBSD: dbopen.3,v 1.28 2015/09/10 10:20:55 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 $Mdocdate: September 10 2015 $ 36.Dt DBOPEN 3 37.Os 38.Sh NAME 39.Nm dbopen 40.Nd database access methods 41.Sh SYNOPSIS 42.In sys/types.h 43.In fcntl.h 44.In limits.h 45.In 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_NOFOLLOW , 84.Dv O_NONBLOCK , 85.Dv O_RDONLY , 86.Dv O_RDWR , 87.Dv O_SHLOCK , 88.Dv O_SYNC , 89and 90.Dv O_TRUNC 91flags are meaningful. 92(Note, opening a database file 93.Dv O_WRONLY 94is not possible.) 95.\"Three additional options may be specified by 96.\".IR or 'ing 97.\"them into the 98.\".I flags 99.\"argument. 100.\".Bl -tag -width XXXXX 101.\".It DB_LOCK 102.\"Do the necessary locking in the database to support concurrent access. 103.\"If concurrent access isn't needed or the database is read-only this 104.\"flag should not be set, as it tends to have an associated performance 105.\"penalty. 106.\".It DB_SHMEM 107.\"Place the underlying memory pool used by the database in shared 108.\"memory. 109.\"Necessary for concurrent access. 110.\".It DB_TXN 111.\"Support transactions in the database. 112.\"The DB_LOCK and DB_SHMEM flags must be set as well. 113.\".El 114.Pp 115The 116.Fa type 117argument is of type 118.Fa DBTYPE 119(as defined in the 120.In db.h 121include file) and may be set to 122.Dv DB_BTREE , 123.Dv DB_HASH , 124or 125.Dv DB_RECNO . 126.Pp 127The 128.Fa openinfo 129argument is a pointer to an access method specific structure described 130in the access method's manual page. 131If 132.Fa openinfo 133is 134.Dv NULL , 135each access method will use defaults appropriate for the system 136and the access method. 137.Pp 138.Fn dbopen 139returns a pointer to a DB structure on success and 140.Dv NULL 141on error. 142The DB structure is defined in the 143.In db.h 144include file, and contains at least the following fields: 145.Bd -literal -offset indent 146typedef struct { 147 DBTYPE type; 148 int (*close)(const DB *db); 149 int (*del)(const DB *db, const DBT *key, 150 unsigned int flags); 151 int (*fd)(const DB *db); 152 int (*get)(const DB *db, DBT *key, DBT *data, 153 unsigned int flags); 154 int (*put)(const DB *db, DBT *key, const DBT *data, 155 unsigned int flags); 156 int (*sync)(const DB *db, u_int flags); 157 int (*seq)(const DB *db, DBT *key, DBT *data, 158 unsigned int flags); 159} DB; 160.Ed 161.Pp 162These elements describe a database type and a set of functions performing 163various actions. 164These functions take a pointer to a structure as returned by 165.Fn dbopen , 166and sometimes one or more pointers to key/data structures and a flag value. 167.Bl -tag -width XXXXX -offset indent 168.It Fa type 169The type of the underlying access method (and file format). 170.It Fa close 171A pointer to a routine to flush any cached information to disk, free any 172allocated resources, and close the underlying file(s). 173Since key/data pairs may be cached in memory, failing to sync the file 174with a 175.Fa close 176or 177.Fa sync 178function may result in inconsistent or lost information. 179.Fa close 180routines return \-1 on error (setting 181.Va errno ) 182and 0 on success. 183.It Fa del 184A pointer to a routine to remove key/data pairs from the database. 185.Pp 186The parameter 187.Fa flags 188may be set to the following value: 189.Bl -tag -width R_NOOVERWRITE 190.It Dv R_CURSOR 191Delete the record referenced by the cursor. 192The cursor must have previously been initialized. 193.El 194.Pp 195.Fa del 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 Fa 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.Fa fd 219routines return \-1 on error (setting 220.Va errno ) 221and the file descriptor on success. 222.It Fa 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.Fa 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.Pp 236.Fa flags 237is currently unused. 238Specifying anything but 0 will result in an error. 239.It Fa put 240A pointer to a routine to store key/data pairs in the database. 241.Pp 242The parameter 243.Fa flags 244may be set to one of the following values: 245.Bl -tag -width R_NOOVERWRITE 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 methods 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.Fa put 301routines is to enter the new key/data pair, replacing any previously 302existing key. 303.Pp 304.Fa put 305routines return \-1 on error (setting 306.Va errno ) , 3070 on success, and 1 if the 308.Dv R_NOOVERWRITE 309flag was set and the key already exists in the file. 310.It Fa seq 311A pointer to a routine which is the interface for sequential 312retrieval from the database. 313The address and length of the key are returned in the structure 314referenced by 315.Fa key , 316and the address and length of the data are returned in the 317structure referenced 318by 319.Fa data . 320.Pp 321Sequential key/data pair retrieval may begin at any time, and the 322position of the 323.Dq cursor 324is not affected by calls to the 325.Fa del , 326.Fa get , 327.Fa put , 328or 329.Fa sync 330routines. 331Modifications to the database during a sequential scan will be reflected 332in the scan, i.e., records inserted behind the cursor will not be returned 333while records inserted in front of the cursor will be returned. 334.Pp 335The 336.Fa flags 337value 338.Sy must 339be set to one of the following values: 340.Bl -tag -width R_NOOVERWRITE 341.It Dv R_CURSOR 342The data associated with the specified key is returned. 343This differs from the 344.Fa get 345routines in that it sets or initializes the cursor to the location of 346the key as well. 347(Note, for the 348.Dv DB_BTREE 349access method, the returned key is not necessarily an 350exact match for the specified key. 351The returned key is the smallest key greater than or equal to the specified 352key, permitting partial key matches and range searches.) 353.It Dv R_FIRST 354The first key/data pair of the database is returned, and the cursor 355is set or initialized to reference it. 356.It Dv R_LAST 357The last key/data pair of the database is returned, and the cursor 358is set or initialized to reference it. 359(Applicable only to the 360.Dv DB_BTREE 361and 362.Dv DB_RECNO 363access methods.) 364.It Dv R_NEXT 365Retrieve the key/data pair immediately after the cursor. 366If the cursor is not yet set, this is the same as the 367.Dv R_FIRST 368flag. 369.It Dv R_PREV 370Retrieve the key/data pair immediately before the cursor. 371If the cursor is not yet set, this is the same as the 372.Dv R_LAST 373flag. 374(Applicable only to the 375.Dv DB_BTREE 376and 377.Dv DB_RECNO 378access methods.) 379.El 380.Pp 381.Dv R_LAST 382and 383.Dv R_PREV 384are available only for the 385.Dv DB_BTREE 386and 387.Dv DB_RECNO 388access methods because they each imply that the keys have an inherent 389order which does not change. 390.Pp 391.Fa seq 392routines return \-1 on error (setting 393.Va errno ) , 3940 on success, and 1 if there are no key/data pairs less than or greater 395than the specified or current key. 396If the 397.Dv DB_RECNO 398access method is being used, and if the database file 399is a character special file and no complete key/data pairs are currently 400available, the 401.Fa seq 402routines return 2. 403.It Fa sync 404A pointer to a routine to flush any cached information to disk. 405If the database is in memory only, the 406.Fa sync 407routine has no effect and will always succeed. 408.Pp 409The 410.Fa flags 411value may be set to the following value: 412.Bl -tag -width R_NOOVERWRITE 413.It Dv R_RECNOSYNC 414If the 415.Dv DB_RECNO 416access method is being used, this flag causes the 417.Fa sync 418routine to apply to the btree file which underlies the 419recno file, not the recno file itself. 420(See the 421.Fa bfname 422field of the 423.Xr recno 3 424manual page for more information.) 425.El 426.Pp 427.Fa 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 -offset indent 436typedef struct { 437 void *data; 438 size_t size; 439} DBT; 440.Ed 441.Pp 442The elements of the DBT structure are defined as follows: 443.Bl -tag -width Ds -offset indent 444.It Fa data 445A pointer to a byte string. 446.It Fa size 447The length of the byte string. 448.El 449.Pp 450Key and data byte strings may reference strings of essentially unlimited 451length although any two of them must fit into available memory at the same 452time. 453It should be noted that the access methods provide no guarantees about 454byte string alignment. 455.Sh ERRORS 456The 457.Fn dbopen 458routine may fail and set 459.Va errno 460for any of the errors specified for the library routines 461.Xr open 2 462and 463.Xr malloc 3 464or the following: 465.Bl -tag -width XEINVALX 466.It Bq Er EFTYPE 467A file is incorrectly formatted. 468.It Bq Er EINVAL 469A parameter has been specified (hash function, pad byte etc.) that is 470incompatible with the current file specification or which is not 471meaningful for the function (for example, use of the cursor without 472prior initialization) or there is a mismatch between the version 473number of the file and the software. 474.El 475.Pp 476The 477.Fa close 478routines may fail and set 479.Va errno 480for any of the errors specified for the library routines 481.Xr close 2 , 482.Xr read 2 , 483.Xr write 2 , 484.Xr free 3 , 485or 486.Xr fsync 2 . 487.Pp 488The 489.Fa del , 490.Fa get , 491.Fa put , 492and 493.Fa seq 494routines may fail and set 495.Va errno 496for any of the errors specified for the library routines 497.Xr read 2 , 498.Xr write 2 , 499.Xr free 3 , 500or 501.Xr malloc 3 . 502.Pp 503The 504.Fa fd 505routines will fail and set 506.Va errno 507to 508.Er ENOENT 509for in-memory databases. 510.Pp 511The 512.Fa sync 513routines may fail and set 514.Va errno 515for any of the errors specified for the library routine 516.Xr fsync 2 . 517.Sh SEE ALSO 518.Xr btree 3 , 519.Xr hash 3 , 520.Xr recno 3 521.Rs 522.%T "LIBTP: Portable, Modular Transactions for UNIX" 523.%A Margo Seltzer 524.%A Michael Olson 525.%J USENIX proceedings 526.%D Winter 1992 527.Re 528.Sh BUGS 529The typedef DBT is a mnemonic for 530.Dq data base thang , 531and was used 532because no one could think of a reasonable name that wasn't already used. 533.Pp 534The file descriptor interface is a kludge and will be deleted in a 535future version of the interface. 536.Pp 537None of the access methods provide any form of concurrent access, 538locking, or transactions. 539