| dbopen.3 (108037) | dbopen.3 (108087) |
|---|---|
| 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. --- 16 unchanged lines hidden (view full) --- 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 | 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. --- 16 unchanged lines hidden (view full) --- 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 |
| 33.\" $FreeBSD: head/lib/libc/db/man/dbopen.3 108037 2002-12-18 12:45:11Z ru $ | 33.\" $FreeBSD: head/lib/libc/db/man/dbopen.3 108087 2002-12-19 09:40:28Z ru $ |
| 34.\" 35.Dd January 2, 1994 36.Dt DBOPEN 3 37.Os 38.Sh NAME 39.Nm dbopen 40.Nd "database access methods" 41.Sh SYNOPSIS --- 22 unchanged lines hidden (view full) --- 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 | 34.\" 35.Dd January 2, 1994 36.Dt DBOPEN 3 37.Os 38.Sh NAME 39.Nm dbopen 40.Nd "database access methods" 41.Sh SYNOPSIS --- 22 unchanged lines hidden (view full) --- 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 file parameter to | 72the 73.Fa file 74argument to |
| 73.Dv NULL . 74.Pp 75The 76.Fa flags 77and 78.Fa mode 79arguments 80are as specified to the --- 94 unchanged lines hidden (view full) --- 175A pointer to a routine to flush any cached information to disk, free any 176allocated resources, and close the underlying file(s). 177Since key/data pairs may be cached in memory, failing to sync the file 178with a 179.Va close 180or 181.Va sync 182function may result in inconsistent or lost information. | 75.Dv NULL . 76.Pp 77The 78.Fa flags 79and 80.Fa mode 81arguments 82are as specified to the --- 94 unchanged lines hidden (view full) --- 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. |
| 183.Va Close | 185.Va close |
| 184routines return -1 on error (setting 185.Va errno ) 186and 0 on success. 187.It Va del 188A pointer to a routine to remove key/data pairs from the database. 189.Pp | 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 |
| 190The parameter | 192The |
| 191.Fa flags | 193.Fa flags |
| 194argument |
|
| 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 | 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 |
| 199.Va Delete | 202.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. --- 17 unchanged lines hidden (view full) --- 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 . | 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. --- 17 unchanged lines hidden (view full) --- 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 . |
| 233.Va Get | 236.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 | 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 |
| 242The parameter | 245The |
| 243.Fa flags | 246.Fa flags |
| 247argument |
|
| 244may be set to one of the following values: 245.Bl -tag -width indent 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 , --- 45 unchanged lines hidden (view full) --- 297This is only true if the keys are ordered and independent, record numbers 298for example. 299.Pp 300The default behavior of the 301.Va put 302routines is to enter the new key/data pair, replacing any previously 303existing key. 304.Pp | 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 , --- 45 unchanged lines hidden (view full) --- 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 |
| 305.Va Put | 309.Va put |
| 306routines return -1 on error (setting 307.Va errno ) , 3080 on success, and 1 if the 309.Dv R_NOOVERWRITE 310flag 311was set and the key already exists in the file. 312.It Va seq 313A pointer to a routine which is the interface for sequential --- 17 unchanged lines hidden (view full) --- 331.Va sync 332routines. 333Modifications to the database during a sequential scan will be reflected 334in the scan, i.e. records inserted behind the cursor will not be returned 335while records inserted in front of the cursor will be returned. 336.Pp 337The 338.Fa flags | 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 --- 17 unchanged lines hidden (view full) --- 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 |
| 339value | 343argument |
| 340.Em must 341be set to one of the following values: 342.Bl -tag -width indent 343.It Dv R_CURSOR 344The data associated with the specified key is returned. 345This differs from the 346.Va get 347routines in that it sets or initializes the cursor to the location of --- 37 unchanged lines hidden (view full) --- 385.Dv R_PREV 386are available only for the 387.Dv DB_BTREE 388and 389.Dv DB_RECNO 390access methods because they each imply that the keys have an inherent 391order which does not change. 392.Pp | 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 --- 37 unchanged lines hidden (view full) --- 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 |
| 393.Va Seq | 397.Va seq |
| 394routines return -1 on error (setting 395.Va errno ) , 3960 on success and 1 if there are no key/data pairs less than or greater 397than the specified or current key. 398If the 399.Dv DB_RECNO 400access method is being used, and if the database file 401is a character special file and no complete key/data pairs are currently 402available, the 403.Va seq 404routines return 2. 405.It Va sync 406A pointer to a routine to flush any cached information to disk. 407If the database is in memory only, the 408.Va sync 409routine has no effect and will always succeed. 410.Pp 411The 412.Fa flags | 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 |
| 413value may be set to the following value: | 417argument may be set to the following value: |
| 414.Bl -tag -width indent 415.It Dv R_RECNOSYNC 416If the 417.Dv DB_RECNO 418access method is being used, this flag causes 419the 420.Va sync 421routine to apply to the btree file which underlies the 422recno file, not the recno file itself. 423(See the 424.Va bfname 425field of the 426.Xr recno 3 427manual page for more information.) 428.El 429.Pp | 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 |
| 430.Va Sync | 434.Va sync |
| 431routines return -1 on error (setting 432.Va errno ) 433and 0 on success. 434.El 435.Sh "KEY/DATA PAIRS" 436Access to all file types is based on key/data pairs. 437Both keys and data are represented by the following data structure: 438.Bd -literal --- 27 unchanged lines hidden (view full) --- 466.Xr open 2 467and 468.Xr malloc 3 469or the following: 470.Bl -tag -width Er 471.It Bq Er EFTYPE 472A file is incorrectly formatted. 473.It Bq Er EINVAL | 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 --- 27 unchanged lines hidden (view full) --- 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 |
| 474A parameter has been specified (hash function, pad byte etc.) that is | 478An argument has been specified (hash function, pad byte etc.) that is |
| 475incompatible with the current file specification or which is not 476meaningful for the function (for example, use of the cursor without 477prior initialization) or there is a mismatch between the version 478number of file and the software. 479.El 480.Pp 481The 482.Va close --- 64 unchanged lines hidden --- | 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 --- 64 unchanged lines hidden --- |