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