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