int DB->key_range(DB *db, DB_TXN *txnid, DBT *key, DB_KEY_RANGE *key_range, u_int32_t flags);
The DB->key_range method 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; for example, if the field less is 0.05, 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 will be non-zero otherwise.
If the operation is to be transaction-protected, the txnid parameter is a transaction handle returned from DB_ENV->txn_begin; otherwise, NULL. The DB->key_range method 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 method returns a non-zero error value on failure and 0 on success.
The DB->key_range method may fail and return a non-zero error for the following conditions:
The underlying database was not of type Btree.
The DB->key_range method 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 method may fail and return DB_RUNRECOVERY, in which case all subsequent Berkeley DB calls will fail in the same way.
Copyright Sleepycat Software