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