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