diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2007-12-14 05:23:00 +0000 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2007-12-14 05:23:00 +0000 |
| commit | 628d8d622922da95dc46828b05e03b942ca334cd (patch) | |
| tree | b12c88e40b0454b48ac984ff769397b32b598db4 | |
| parent | f88233dd6c1033034b03dd4d9dcb38c24c66e141 (diff) | |
| download | man-pages-628d8d622922da95dc46828b05e03b942ca334cd.tar.gz | |
ffix
| -rw-r--r-- | man3/btree.3 | 19 | ||||
| -rw-r--r-- | man3/dbopen.3 | 127 |
2 files changed, 105 insertions, 41 deletions
diff --git a/man3/btree.3 b/man3/btree.3 index b9932c535d..e3f3de31ac 100644 --- a/man3/btree.3 +++ b/man3/btree.3 @@ -83,16 +83,23 @@ The flag value is specified by any of the following values: .RS .TP -R_DUP +.B R_DUP Permit duplicate keys in the tree, that is, permit insertion if the key to be inserted already exists in the tree. The default behavior, as described in .BR dbopen (3), is to overwrite a matching key when inserting a new key or to fail if -the R_NOOVERWRITE flag is specified. -The R_DUP flag is overridden by the R_NOOVERWRITE flag, and if the -R_NOOVERWRITE flag is specified, attempts to insert duplicate keys into +the +.B R_NOOVERWRITE +flag is specified. +The +.B R_DUP +flag is overridden by the +.B R_NOOVERWRITE +flag, and if the +.B R_NOOVERWRITE flag +is specified, attempts to insert duplicate keys into the tree will fail. .IP If the database contains duplicate keys, the order of retrieval of @@ -100,7 +107,9 @@ key/data pairs is undefined if the .I get routine is used, however, .I seq -routine calls with the R_CURSOR flag set will always return the logical +routine calls with the +.B R_CURSOR +flag set will always return the logical ``first'' of any group of duplicate keys. .RE .TP diff --git a/man3/dbopen.3 b/man3/dbopen.3 index cecbd4ab8e..eb6aec2f92 100644 --- a/man3/dbopen.3 +++ b/man3/dbopen.3 @@ -115,7 +115,11 @@ argument is of type (as defined in the .I <db.h> include file) and -may be set to DB_BTREE, DB_HASH or DB_RECNO. +may be set to +.BR DB_BTREE , +.BR DB_HASH , +or +.BR DB_RECNO . .PP The .I openinfo @@ -133,6 +137,7 @@ The DB structure is defined in the include file, and contains at least the following fields: .sp +.in +0.5i .nf typedef struct { DBTYPE type; @@ -146,6 +151,7 @@ typedef struct { int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); } DB; .fi +.in .PP These elements describe a database type and a set of functions performing various actions. @@ -178,7 +184,7 @@ The parameter may be set to the following value: .RS .TP -R_CURSOR +.B R_CURSOR Delete the record referenced by the cursor. The cursor must have previously been initialized. .RE @@ -234,42 +240,59 @@ The parameter may be set to one of the following values: .RS .TP -R_CURSOR +.B R_CURSOR Replace the key/data pair referenced by the cursor. The cursor must have previously been initialized. .TP -R_IAFTER +.B R_IAFTER Append the data immediately after the data referenced by .IR key , creating a new key/data pair. The record number of the appended key/data pair is returned in the .I key structure. -(Applicable only to the DB_RECNO access method.) +(Applicable only to the +.B DB_RECNO +access method.) .TP -R_IBEFORE +.B R_IBEFORE Insert the data immediately before the data referenced by .IR key , creating a new key/data pair. The record number of the inserted key/data pair is returned in the .I key structure. -(Applicable only to the DB_RECNO access method.) +(Applicable only to the +.B DB_RECNO +access method.) .TP -R_NOOVERWRITE +.B R_NOOVERWRITE Enter the new key/data pair only if the key does not previously exist. .TP -R_SETCURSOR +.B R_SETCURSOR Store the key/data pair, setting or initializing the position of the cursor to reference it. -(Applicable only to the DB_BTREE and DB_RECNO access methods.) +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) .RE .IP -R_SETCURSOR is available only for the DB_BTREE and DB_RECNO access +.B R_SETCURSOR +is available only for the +.B DB_BTREE +and +.B DB_RECNO +access methods because it implies that the keys have an inherent order which does not change. .IP -R_IAFTER and R_IBEFORE are available only for the DB_RECNO +.B R_IAFTER +and +.B R_IBEFORE +are available only for the +.B DB_RECNO access method because they each imply that the access method is able to create new keys. This is only true if the keys are ordered and independent, record numbers @@ -283,7 +306,8 @@ existing key. .I Put routines return \-1 on error (setting .IR errno ), -0 on success, and 1 if the R_NOOVERWRITE +0 on success, and 1 if the +.B R_NOOVERWRITE .I flag was set and the key already exists in the file. .TP @@ -316,37 +340,57 @@ The flag value be set to one of the following values: .RS .TP -R_CURSOR +.B R_CURSOR The data associated with the specified key is returned. This differs from the .I get routines in that it sets or initializes the cursor to the location of the key as well. -(Note, for the DB_BTREE access method, the returned key is not necessarily an +(Note, for the +.B DB_BTREE +access method, the returned key is not necessarily an exact match for the specified key. The returned key is the smallest key greater than or equal to the specified key, permitting partial key matches and range searches.) .TP -R_FIRST +.B R_FIRST The first key/data pair of the database is returned, and the cursor is set or initialized to reference it. .TP -R_LAST +.B R_LAST The last key/data pair of the database is returned, and the cursor is set or initialized to reference it. -(Applicable only to the DB_BTREE and DB_RECNO access methods.) +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) .TP -R_NEXT +.B R_NEXT Retrieve the key/data pair immediately after the cursor. -If the cursor is not yet set, this is the same as the R_FIRST flag. +If the cursor is not yet set, this is the same as the +.B R_FIRST +flag. .TP -R_PREV +.B R_PREV Retrieve the key/data pair immediately before the cursor. -If the cursor is not yet set, this is the same as the R_LAST flag. -(Applicable only to the DB_BTREE and DB_RECNO access methods.) +If the cursor is not yet set, this is the same as the +.B R_LAST +flag. +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) .RE .IP -R_LAST and R_PREV are available only for the DB_BTREE and DB_RECNO +.B R_LAST +and +.B R_PREV +are available only for the +.B DB_BTREE +and +.B DB_RECNO access methods because they each imply that the keys have an inherent order which does not change. .IP @@ -355,7 +399,9 @@ routines return \-1 on error (setting .IR errno ), 0 on success and 1 if there are no key/data pairs less than or greater than the specified or current key. -If the DB_RECNO access method is being used, and if the database file +If the +.B DB_RECNO +access method is being used, and if the database file is a character special file and no complete key/data pairs are currently available, the .I seq @@ -370,8 +416,10 @@ routine has no effect and will always succeed. The flag value may be set to the following value: .RS .TP -R_RECNOSYNC -If the DB_RECNO access method is being used, this flag causes +.B R_RECNOSYNC +If the +.B DB_RECNO +access method is being used, this flag causes the sync routine to apply to the btree file which underlies the recno file, not the recno file itself. (See the @@ -388,16 +436,19 @@ and 0 on success. .SS "Key/Data Pairs" Access to all file types is based on key/data pairs. Both keys and data are represented by the following data structure: -.PP +.in +0.5i +.nf + typedef struct { -.RS -void *data; -.br -size_t size; -.RE + void *data; + size_t size; } DBT; +.fi +.in .PP -The elements of the DBT structure are defined as follows: +The elements of the +.I DBT +structure are defined as follows: .TP data A pointer to a byte string. @@ -462,7 +513,9 @@ The .I fd routines will fail and set .I errno -to ENOENT for in memory databases. +to +.B ENOENT +for in memory databases. .PP The .I sync @@ -471,7 +524,9 @@ routines may fail and set for any of the errors specified for the library routine .BR fsync (2). .SH BUGS -The typedef DBT is a mnemonic for ``data base thang'', and was used +The typedef +.I DBT +is a mnemonic for ``data base thang'', and was used because no-one could think of a reasonable name that wasn't already used. .PP The file descriptor interface is a kludge and will be deleted in a |