err_P.
Negative integers are used for errors according to increasingly severity, as follows:
The bsiz of a segment (given in call to make_seg)
is a parameter crucial for performance; balancing CPU time traversing
blocks with file-system latency. bsiz should be an
integer multiple of the file-system block size.
In the 1990s our nominal bsiz was 2.kiB; now it should probably be 4.kiB, 8.kiB, or 16.kiB.
seg should be a non-negative number. Opens the database seg in filename and returns seg if successful, a status code otherwise. The database seg will be read-only if the mode argument is 0. It will be read-write if the mode argument is 2.
Closes database segment seg and the file containing it. If hammer_P is NULL, then if there are any problems freeing buffers, then the close is aborted. A status code is returned.
The integer seg must specify an unused segment. The integer bsiz specifies the size of B-tree blocks. bsiz should be an integer multiple of the file-system block size. Nominal value is 4096.
makeSeg makes a new empty database named filename. A status code is returned.
Call openSeg to use the new database.
The write-control-bits argument (wcb) to these functions controls the latency of updates to the file after various operations. These bits are defined as follows:
| value | C-name | Meaning |
| 1 | wcb_sap | save block after PUTs |
| 2 | wcb_sar | save block after REMOVEs |
| 4 | wcb_sac | force block save after cached block changes |
| 8 | wcb_fac | flush buffer entirely after cached block changes (not currently implemented) |
btCreate can be used to create temporary b-trees. Temporary trees will be
be reclaimed by check program after system crashes. In order to
make a tree persistent, add it to a directory (tree).
Currently, btClose has no effect other than to clear han.
Note: most of the data-manipulating commands here can return notpres, with the followng meanings:
bt-get |
no such key. |
bt-next |
no NEXT key (ie, key given was LAST key). |
bt-prev |
no PREV key (ie, key given was FIRST key). |
bt-rem |
KEY was not found. |
bt-put |
NOT USED (could be symmetric w/WRITE). |
bt-write |
key WAS found, so no write done. |
btGet stores into the string ansStr the
value associated with keyStr in tree han. btGet returns the length of the
string stored into ansStr or an error code.
btNext stores into the string ansStr the
next key after keyStr in tree han. btNext returns the length of the string
stored into ansStr or an error code.
btPrev stores into the string ansStr the
last key before keyStr in tree han. btPrev returns the length of the string
stored into ansStr or an error code.
btRem stores into the string ansStr the
value associated with keyStr in tree han; then removes that association
from tree han. btRem returns the length of the string stored into ansStr or
an error code.
If ansStr is 0, btRem removes the keyStr association from tree han and returns
SUCCESS if successful; an error code if not.
btRemRange removes [keyStr ... key2Str) and their values. If key2Str <= keyStr no
deletion will occur (even if keyStr is found). btRemRange returns SUCCESS if
the operation is complete, an error status code if not.
btPut
makes the value associated with keyStr be valStr in tree han. btPut returns a
status code for the operation.
btWrite does not modify
the tree and returns the notpres status code.
Otherwise, btWrite makes the value associated with keyStr be valStr in tree han.
btWrite returns a status code for the operation.
btScan scans all keys in the range [kstr1..kstr2),
performing one of several functions:
| operation | func | RESULT |
| COUNT-SCAN | NIL | counts all keys in range |
| COUNT-SCAN | given | counts all keys in range satisfying func |
| REM-SCAN | NIL | deletes all keys in range |
| REM-SCAN | given | deletes all keys in range satisfying func |
| MODIFY-SCAN | NIL | ARGERR |
| MODIFY-SCAN | given | updates values for keys in range satisfying func |
btScan returns SUCCESS if scan completed; under any other result code
the scan is resumable. The possible results are:
Each block of data is scanned/deleted/modified in a single operation that is, the block is found and locked only once, and only written after all modifications are made. Tho only exception is that MODIFY-SCANs that increase the size of values can cause block splits. Such cases are detected and converted to a PUT plus a NEXT. This has two consequences: data is written out each time a PUT occurs, and it is conceivable that func may be called more than once on the key value that caused the split if a RETRYERR occurs in the PUT. However, SCAN guarantees that only one modification will actually be made in this case (so that one can write INCREMENT-RANGE, for example).
func is passed pointers to (copies of) the key and value, plus one user argument:
func (keystr klen vstr vlen extra_arg);
func is expected to return either: SUCCESS for DELETE/COUNT, NOTPRES/NOTDONE for SKIP (ie, DONT DELETE/COUNT), or any other code to terminate the scan resumably at the current point. For MODIFY-SCAN, if changing the value, the new value length is returned. Except for the case mentioned above, the caller can depend on func being called exactly once for each key value in the specified range, and only on those values.
If kstr2 <= kstr1, then no scan will occur (even if kstr1 is found).
To make possible bounded-time operation btScan will
access at most blkLimit blocks at a time; if you dont care,
give it -1 for blkLimit.
The number of keys deleted/counted/modified is returned in the
skey-count field of respkt; the key to resume at is returned in
kstr1 (which therefore needs to be 256 bytes long); and the
new key length is returned in the skey-len field of respkt. If
returns SUCCESS, skey-len is zero. NOTE that
skey-count is cumulative, so the caller needs to initialize
it to 0 when starting a new btScan.
WARNING: when btScan returns other than SUCCESS, it modifies
the kstr1 string so that the string args are correctly set up for the
next call (the returned value is the new length for kstr1).
Therefore, kstr1 must be a maximum-length string!