The DB->key_range function returns an estimate of the proportion of keys
that are less than, equal to and greater than the specified key. The
underlying database must be of type Btree.
The information is returned in the key_range argument, which
contains three elements of type double, less, equal and
greater. Values are in the range of 0 to 1, e.g., if the field
less is 0.05, that indicates that 5% of the keys in the database
are less than the key argument. The value for equal will be zero
if there is no matching key and non-zero otherwise.
If the file is being accessed under transaction protection, the
txnid parameter is a transaction ID returned from
txn_begin, otherwise, NULL.
The DB->key_range function does not retain the locks it acquires for the
life of the transaction, so estimates may not be repeatable.
The flags parameter is currently unused, and must be set to 0.
The DB->key_range function returns a non-zero error value on failure and 0 on success.
Errors
The DB->key_range function may fail and return a non-zero error for the following conditions:
DB_LOCK_DEADLOCK
The operation was selected to resolve a deadlock.
EINVAL
An invalid flag value or parameter was specified.
The underlying database was not of type Btree.
The DB->key_range function may fail and return a non-zero error for errors specified for other Berkeley DB and C library or system functions.
If a catastrophic error has occurred, the DB->key_range function may fail and return
DB_RUNRECOVERY, in which case all subsequent Berkeley DB calls will fail
in the same way.