# C API

This API provides a very low-level interface to FoundationDB. It is primarily intended for use in implementing higher level APIs, rather than for direct use. If you are new to FoundationDB, you are probably better served by reading one of the other APIs first.

## Installation

FoundationDB’s C bindings are installed with the FoundationDB client binaries (see Installing FoundationDB client binaries).

On Linux,
  `fdb_c.h` is installed into `/usr/include/foundationdb/`
  `libfdb_c.so` is installed into `/usr/lib/`
On macOS,
  `fdb_c.h` is installed into `/usr/local/include/foundationdb/`
  `libfdb_c.dylib` is installed into `/usr/local/lib/`

## Linking

The FoundationDB C bindings are provided as a shared object which may be linked against at build time, or dynamically loaded at runtime. Any program that uses this API must be able to find a platform-appropriate shared library at runtime. Generally, this condition is best met by installing the FoundationDB client binaries (see Installing FoundationDB client binaries) on any machine where the program will be run.

### Linux

When linking against `libfdb_c.so`, you must also link against `libm`, `libpthread` and `librt`. These dependencies will be resolved by the dynamic linker when using this API via `dlopen()` or an FFI.

### macOS

When linking against `libfdb_c.dylib`, no additional libraries are required.

## API versioning

Prior to including `fdb_c.h`, you must define the `FDB_API_VERSION` macro. This, together with the `fdb_select_api_version()` function, allows programs written against an older version of the API to compile and run with newer versions of the C library. The current version of the FoundationDB C API is 520.

    #define FDB_API_VERSION 520
    #include <foundationdb/fdb_c.h>

fdb_error_t `fdb_select_api_version`(int version)

  Must be called before any other API functions. `version` must be less than or equal to `FDB_API_VERSION` (and should almost always be equal).

  Language bindings implemented in C which themselves expose API versioning will usually pass the version requested by the application, instead of always passing `FDB_API_VERSION`.

  Passing a version less than `FDB_API_VERSION` will cause the API to behave as it did in the older version.

  It is an error to call this function after it has returned successfully. It is not thread safe, and if called from more than one thread simultaneously its behavior is undefined.

  Note

  This is actually implemented as a macro. If you are accessing this API via `dlopen()` or an FFI, you will need to use `fdb_select_api_version_impl()`.

  Warning

  When using the multi-version client API, setting an API version that is not supported by a particular client library will prevent that client from being used to connect to the cluster. In particular, you should not advance the API version of your application after upgrading your client until the cluster has also been upgraded.

fdb_error_t `fdb_select_api_version_impl`(int runtime_version, int header_version)

  This is the actual entry point called by the `fdb_select_api_version()` macro. It should never be called directly from C, but if you are accessing this API via `dlopen()` or an FFI, you will need to use it. `fdb_select_api_version(v)` is equivalent to `fdb_select_api_version_impl(v, FDB_API_VERSION)`.

  It is an error to call this function after it has returned successfully. It is not thread safe, and if called from more than one thread simultaneously its behavior is undefined.

  `runtime_version`

    The version of run-time behavior the API is requested to provide. Must be less than or equal to `header_version`, and should almost always be equal.

    Language bindings which themselves expose API versioning will usually pass the version requested by the application.

  `header_version`
    The version of the ABI (application binary interface) that the calling code expects to find in the shared library. If you are using an FFI, this must correspond to the version of the API you are using as a reference (currently 520). For example, the number of arguments that a function takes may be affected by this value, and an incorrect value is unlikely to yield success.

  Warning

  When using the multi-version client API, setting an API version that is not supported by a particular client library will prevent that client from being used to connect to the cluster. In particular, you should not advance the API version of your application after upgrading your client until the cluster has also been upgraded.

int `fdb_get_max_api_version`()

  Returns `FDB_API_VERSION`, the current version of the FoundationDB C API. This is the maximum version that may be passed to `fdb_select_api_version()`.

## Network

The FoundationDB client library performs most tasks on a singleton thread (which usually will be a different thread than your application runs on). These functions are used to configure, start and stop the FoundationDB event loop on this thread.

fdb_error_t `fdb_network_set_option`( FDBNetworkOption option, uint8_t const* value, int value_length)

  Called to set network options. If the given option is documented as taking a parameter, you must also pass a pointer to the parameter value and the parameter value’s length. If the option is documented as taking an `Int` parameter, `value` must point to a signed 64-bit integer (little-endian), and `value_length` must be 8. This memory only needs to be valid until `fdb_network_set_option()` returns.

`FDBNetworkOption`

  Please see `fdb_c_options.g.h` for a definition of this type, along with documentation of its allowed values.

fdb_error_t `fdb_setup_network`()

  Must be called after `fdb_select_api_version()` (and zero or more calls to `fdb_network_set_option()`) and before any other function in this API. `fdb_setup_network()` can only be called once.

fdb_error_t `fdb_add_network_thread_completion_hook`(void (*hook)(void*), void *hook_parameter)

  Must be called after `fdb_setup_network()` and prior to `fdb_run_network()` if called at all. This will register the given callback to run at the completion of the network thread. If there are multiple network threads running (which might occur if one is running multiple versions of the client, for example), then the callback is invoked once on each thread. When the supplied function is called, the supplied parameter is passed to it.

fdb_error_t `fdb_run_network`()

  Must be called after `fdb_setup_network()` before any asynchronous functions in this API can be expected to complete. Unless your program is entirely event-driven based on results of asynchronous functions in this API and has no event loop of its own, you will want to invoke this function on an auxiliary thread (which it is your responsibility to create).

  This function will not return until `fdb_stop_network()` is called by you or a serious error occurs. You must not invoke `fdb_run_network()` concurrently or reentrantly while it is already running.

fdb_error_t `fdb_stop_network`()

  Signals the event loop invoked by `fdb_run_network()` to terminate. You must call this function and wait for `fdb_run_network()` to return before allowing your program to exit, or else the behavior is undefined. For example, when running `fdb_run_network()` on a thread (using pthread), this will look like:

      pthread_t network_thread; /* handle for thread which invoked fdb_run_network() */
      int err;

      ...

      err = fdb_stop_network();
      if ( err ) {
          /* An error occurred (probably network not running) */
      }
      err = pthread_join( network_thread, NULL );
      if ( err ) {
          /* Unknown error */
      }
      exit(0);

  This function may be called from any thread. Once the network is stopped it cannot be restarted during the lifetime of the running program.

## Future

Most functions in the FoundationDB API are asynchronous, meaning that they may return to the caller before actually delivering their result. These functions always return `FDBFuture*`. An `FDBFuture` object represents a result value or error to be delivered at some future time. You can wait for a Future to be “ready” – to have a value or error delivered – by setting a callback function, or by blocking a thread, or by polling. Once a Future is ready, you can extract either an error code or a value of the appropriate type (the documentation for the original function will tell you which `fdb_future_get_*()` function you should call).

To use the API in a synchronous way, you would typically do something like this for each asynchronous call:

    // Call an API that returns FDBFuture*, documented as returning type foo in the future
    f = fdb_something();

    // Wait for the Future to be *ready*
    if ( (fdb_future_block_until_ready(f)) != 0 ) {
        // Exceptional error (e.g. out of memory)
    }

    if ( (err = fdb_future_get_foo(f, &result)) == 0 ) {
        // Use result
        // In some cases, you must be finished with result before calling
        // fdb_future_destroy() (see the documentation for the specific
        // fdb_future_get_*() method)
    } else {
        // Handle the error. If this is an error in a transaction, see
        // fdb_transaction_on_error()
    }

    fdb_future_destroy(f);

Futures make it easy to do multiple operations in parallel, by calling several asynchronous functions before waiting for any of the results. This can be important for reducing the latency of transactions.

See Programming with futures for further (language-independent) discussion.

`FDBFuture`

  An opaque type that represents a Future in the FoundationDB C API.

void `fdb_future_cancel`( FDBFuture* future)

  Cancels an `FDBFuture` object and its associated asynchronous operation. If called before the future is ready, attempts to access its value will return an operation_cancelled error. Cancelling a future which is already ready has no effect. Note that even if a future is not ready, its associated asynchronous operation may have succesfully completed and be unable to be cancelled.

void `fdb_future_destroy`( FDBFuture* future)

  Destroys an `FDBFuture` object. It must be called exactly once for each FDBFuture* returned by an API function. It may be called before or after the future is ready. It will also cancel the future (and its associated operation if the latter is still outstanding).

fdb_error_t `fdb_future_block_until_ready`( FDBFuture* future)

  Blocks the calling thread until the given Future is ready. It will return success even if the Future is set to an error – you must call `fdb_future_get_error()` to determine that. `fdb_future_block_until_ready()` will return an error only in exceptional conditions (e.g. out of memory or other operating system resources).

  Warning

  Never call this function from a callback passed to `fdb_future_set_callback()`. This may block the thread on which `fdb_run_network()` was invoked, resulting in a deadlock.

fdb_bool_t `fdb_future_is_ready`( FDBFuture* future)

  Returns non-zero if the Future is ready. A Future is ready if it has been set to a value or an error.

fdb_error_t `fdb_future_set_callback`( FDBFuture* future, FDBCallback callback, void* callback_parameter)

  Causes the `FDBCallback` function to be invoked as `callback(future, callback_parameter)` when the given Future is ready. If the Future is already ready, the call may occur in the current thread before this function returns (but this behavior is not guaranteed). Alternatively, the call may be delayed indefinitely and take place on the thread on which `fdb_run_network()` was invoked, and the callback is responsible for any necessary thread synchronization (and/or for posting work back to your application event loop, thread pool, etc. if your application’s architecture calls for that).

  Warning

  Never call `fdb_future_block_until_ready()` from a callback passed to this function. This may block the thread on which `fdb_run_network()` was invoked, resulting in a deadlock.

`FDBCallback`

  A pointer to a function which takes `FDBFuture*` and `void*` and returns `void`.

void `fdb_future_release_memory`( FDBFuture* future)

  Note

  This function provides no benefit to most application code. It is designed for use in writing generic, thread-safe language bindings. Applications should normally call `fdb_future_destroy()` only.

  This function may only be called after a successful (zero return value) call to `fdb_future_get_key()`, `fdb_future_get_value()`, or `fdb_future_get_keyvalue_array()`. It indicates that the memory returned by the prior get call is no longer needed by the application. After this function has been called the same number of times as `fdb_future_get_*()`, further calls to `fdb_future_get_*()` will return a future_released error. It is still necessary to later destroy the future with `fdb_future_destroy()`.

  Calling this function is optional, since `fdb_future_destroy()` will also release the memory returned by get functions. However, `fdb_future_release_memory()` leaves the future object itself intact and provides a specific error code which can be used for coordination by multiple threads racing to do something with the results of a specific future. This has proven helpful in writing binding code.

fdb_error_t `fdb_future_get_error`( FDBFuture* future)

  Returns zero if `future` is ready and not in an error state, and a non-zero error code otherwise.

fdb_error_t `fdb_future_get_version`( FDBFuture* future, int64_t* out_version)

  Extracts a value of type version from an `FDBFuture` into a caller-provided variable of type `int64_t`. `future` must represent a result of the appropriate type (i.e. must have been returned by a function documented as returning this type), or the results are undefined.

  Returns zero if `future` is ready and not in an error state, and a non-zero error code otherwise (in which case the value of any out parameter is undefined).

fdb_error_t `fdb_future_get_key`( FDBFuture* future, uint8_t const** out_key, int* out_key_length)

  Extracts a value of type key from an `FDBFuture` into caller-provided variables of type `uint8_t*` (a pointer to the beginning of the key) and `int` (the length of the key). `future` must represent a result of the appropriate type (i.e. must have been returned by a function documented as returning this type), or the results are undefined.

  Returns zero if `future` is ready and not in an error state, and a non-zero error code otherwise (in which case the value of any out parameter is undefined).

  The memory referenced by the result is owned by the `FDBFuture` object and will be valid until either `fdb_future_destroy(future)` or `fdb_future_release_memory(future)` is called.

fdb_error_t `fdb_future_get_cluster`( FDBFuture* future, FDBCluster** out_cluster)

  Extracts a value of type `FDBCluster*` from an `FDBFuture` into a caller-provided variable. `future` must represent a result of the appropriate type (i.e. must have been returned by a function documented as returning this type), or the results are undefined.

  Returns zero if `future` is ready and not in an error state, and a non-zero error code otherwise (in which case the value of any out parameter is undefined).

  This function may only be called once on a given `FDBFuture` object, as it transfers ownership of the `FDBCluster` to the caller. The caller is responsible for calling `fdb_cluster_destroy()` when finished with the result.

fdb_error_t `fdb_future_get_database`( FDBFuture* future, FDBDatabase** out_database)

  Extracts a value of type `FDBDatabase*` from an `FDBFuture` into a caller-provided variable. `future` must represent a result of the appropriate type (i.e. must have been returned by a function documented as returning this type), or the results are undefined.

  Returns zero if `future` is ready and not in an error state, and a non-zero error code otherwise (in which case the value of any out parameter is undefined).

  This function may only be called once on a given `FDBFuture` object, as it transfers ownership of the `FDBDatabase` to the caller. The caller is responsible for calling `fdb_database_destroy(*out_database)` when finished with the result.

fdb_error_t `fdb_future_get_value`( FDBFuture* future, fdb_bool_t* out_present, uint8_t const** out_value, int* out_value_length)

  Extracts a database value from an `FDBFuture` into caller-provided variables. `future` must represent a result of the appropriate type (i.e. must have been returned by a function documented as returning this type), or the results are undefined.

  Returns zero if `future` is ready and not in an error state, and a non-zero error code otherwise (in which case the value of any out parameter is undefined).

  `*out_present`
    Set to non-zero if (and only if) the requested value was present in the database. (If zero, the other outputs are meaningless.)
  `*out_value`
    Set to point to the first byte of the value.
  `*out_value_length`
    Set to the length of the value (in bytes).

  The memory referenced by the result is owned by the `FDBFuture` object and will be valid until either `fdb_future_destroy(future)` or `fdb_future_release_memory(future)` is called.

fdb_error_t `fdb_future_get_string_array`( FDBFuture* future, const char*** out_strings, int* out_count)

  Extracts an array of null-terminated C strings from an `FDBFuture` into caller-provided variables. `future` must represent a result of the appropriate type (i.e. must have been returned by a function documented as returning this type), or the results are undefined.

  Returns zero if `future` is ready and not in an error state, and a non-zero error code otherwise (in which case the value of any out parameter is undefined).

  `*out_strings`
    Set to point to the first string in the array.
  `*out_count`
    Set to the number of strings in the array.

  The memory referenced by the result is owned by the `FDBFuture` object and will be valid until either `fdb_future_destroy(future)` or `fdb_future_release_memory(future)` is called.

fdb_error_t `fdb_future_get_keyvalue_array`( FDBFuture* future, FDBKeyValue const** out_kv, int* out_count, fdb_bool_t* out_more)

  Extracts an array of `FDBKeyValue` objects from an `FDBFuture` into caller-provided variables. `future` must represent a result of the appropriate type (i.e. must have been returned by a function documented as returning this type), or the results are undefined.

  Returns zero if `future` is ready and not in an error state, and a non-zero error code otherwise (in which case the value of any out parameter is undefined).

  `*out_kv`
    Set to point to the first `FDBKeyValue` object in the array.
  `*out_count`
    Set to the number of `FDBKeyValue` objects in the array.
  `*out_more`
    Set to true if (but not necessarily only if) values remain in the key range requested (possibly beyond the limits requested).

  The memory referenced by the result is owned by the `FDBFuture` object and will be valid until either `fdb_future_destroy(future)` or `fdb_future_release_memory(future)` is called.

`FDBKeyValue`

  Represents a single key-value pair in the output of `fdb_future_get_keyvalue_array()`.

      typedef struct {
          const void* key;
          int         key_length;
          const void* value;
          int         value_length;
      } FDBKeyValue;

  `key`
    A pointer to a key.
  `key_length`
    The length of the key pointed to by `key`.
  `value`
    A pointer to a value.
  `value_length`
    The length of the value pointed to by `value`.

## Cluster

`FDBCluster`

  An opaque type that represents a Cluster in the FoundationDB C API.

FDBFuture* `fdb_create_cluster`(const char* cluster_file_path)

  Returns an `FDBFuture` which will be set to an `FDBCluster` object. You must first wait for the `FDBFuture` to be ready, check for errors, call `fdb_future_get_cluster()` to extract the `FDBCluster` object, and then destroy the `FDBFuture` with `fdb_future_destroy()`.

  `cluster_file_path`
    A NULL-terminated string giving a local path of a cluster file (often called ‘fdb.cluster’) which contains connection information for the FoundationDB cluster. If cluster_file_path is NULL or an empty string, then a default cluster file will be used.

void `fdb_cluster_destroy`( FDBCluster* cluster)

  Destroys an `FDBCluster` object. It must be called exactly once for each successful call to `fdb_future_get_cluster()`. This function only destroys a handle to the cluster – your cluster will be fine!

fdb_error_t `fdb_cluster_set_option`( FDBCluster* cluster, FDBClusterOption option, uint8_t const* value, int value_length)

  Called to set an option on an `FDBCluster`. If the given option is documented as taking a parameter, you must also pass a pointer to the parameter value and the parameter value’s length. If the option is documented as taking an `Int` parameter, `value` must point to a signed 64-bit integer (little-endian), and `value_length` must be 8. This memory only needs to be valid until `fdb_cluster_set_option()` returns.

`FDBClusterOption`

  Please see `fdb_c_options.g.h` for a definition of this type, along with documentation of its allowed values.

FDBFuture* `fdb_cluster_create_database`( FDBCluster *cluster, uint8_t const* db_name, int db_name_length)

  Returns an `FDBFuture` which will be set to an `FDBDatabase` object. You must first wait for the `FDBFuture` to be ready, check for errors, call `fdb_future_get_database()` to extract the `FDBDatabase` object, and then destroy the `FDBFuture` with `fdb_future_destroy()`.

  `db_name`
    A pointer to the name of the database to be opened. The value does not need to be NULL-terminated. In the current FoundationDB API, the database name must be “DB”.
  `db_name_length`
    The length of the parameter specified by `db_name`.

## Database

An `FDBDatabase` represents a FoundationDB database — a mutable, lexicographically ordered mapping from binary keys to binary values. Modifications to a database are performed via transactions.

`FDBDatabase`

  An opaque type that represents a database in the FoundationDB C API.

void `fdb_database_destroy`( FDBDatabase* database)

  Destroys an `FDBDatabase` object. It must be called exactly once for each successful call to `fdb_future_get_database()`. This function only destroys a handle to the database – your database will be fine!

fdb_error_t `fdb_database_set_option`( FDBDatabase* database, FDBDatabaseOption option, uint8_t const* value, int value_length)

  Called to set an option an on `FDBDatabase`. If the given option is documented as taking a parameter, you must also pass a pointer to the parameter value and the parameter value’s length. If the option is documented as taking an `Int` parameter, `value` must point to a signed 64-bit integer (little-endian), and `value_length` must be 8. This memory only needs to be valid until `fdb_database_set_option()` returns.

`FDBDatabaseOption`

  Please see `fdb_c_options.g.h` for a definition of this type, along with documentation of its allowed values.

fdb_error_t `fdb_database_create_transaction`( FDBDatabase* database, FDBTransaction** out_transaction)

  Creates a new transaction on the given database. The caller assumes ownership of the `FDBTransaction` object and must destroy it with `fdb_transaction_destroy()`.

  `*out_transaction`
    Set to point to the newly created `FDBTransaction`.

## Transaction

In FoundationDB, a transaction is a mutable snapshot of a database. All read and write operations on a transaction see and modify an otherwise-unchanging version of the database and only change the underlying database if and when the transaction is committed. Read operations do see the effects of previous write operations on the same transaction. Committing a transaction usually succeeds in the absence of conflicts.

Applications must provide error handling and an appropriate retry loop around the application code for a transaction. See the documentation for `fdb_transaction_on_error()`.

Transactions group operations into a unit with the properties of atomicity, isolation, and durability. Transactions also provide the ability to maintain an application’s invariants or integrity constraints, supporting the property of consistency. Together these properties are known as ACID.

Transactions are also causally consistent: once a transaction has been successfully committed, all subsequently created transactions will see the modifications made by it.

`FDBTransaction`

  An opaque type that represents a transaction in the FoundationDB C API.

void `fdb_transaction_destroy`( FDBTransaction* transaction)

  Destroys an `FDBTransaction` object. It must be called exactly once for each successful call to `fdb_database_create_transaction()`. Destroying a transaction which has not had `fdb_transaction_commit()` called implicitly “rolls back” the transaction (sets and clears do not take effect on the database).

fdb_error_t `fdb_transaction_set_option`( FDBTransaction* transaction, FDBTransactionOption option, uint8_t const* value, int value_length)

  Called to set an option on an `FDBTransaction`. If the given option is documented as taking a parameter, you must also pass a pointer to the parameter value and the parameter value’s length. If the option is documented as taking an `Int` parameter, `value` must point to a signed 64-bit integer (little-endian), and `value_length` must be 8. This memory only needs to be valid until `fdb_transaction_set_option()` returns.

`FDBTransactionOption`

  Please see `fdb_c_options.g.h` for a definition of this type, along with documentation of its allowed values.

void `fdb_transaction_set_read_version`( FDBTransaction* transaction, int64_t version)

  Sets the snapshot read version used by a transaction. This is not needed in simple cases. If the given version is too old, subsequent reads will fail with error_code_past_version; if it is too new, subsequent reads may be delayed indefinitely and/or fail with error_code_future_version. If any of `fdb_transaction_get_*()` have been called on this transaction already, the result is undefined.

FDBFuture* `fdb_transaction_get_read_version`( FDBTransaction* transaction)

  Returns an `FDBFuture` which will be set to the transaction snapshot read version. You must first wait for the `FDBFuture` to be ready, check for errors, call `fdb_future_get_version()` to extract the version into an int64_t that you provide, and then destroy the `FDBFuture` with `fdb_future_destroy()`.

  The transaction obtains a snapshot read version automatically at the time of the first call to `fdb_transaction_get_*()` (including this one) and (unless causal consistency has been deliberately compromised by transaction options) is guaranteed to represent all transactions which were reported committed before that call.

FDBFuture* `fdb_transaction_get`( FDBTransaction* transaction, uint8_t const* key_name, int key_name_length, fdb_bool_t snapshot)

  Reads a value from the database snapshot represented by `transaction`.

  Returns an `FDBFuture` which will be set to the value of `key_name` in the database. You must first wait for the `FDBFuture` to be ready, check for errors, call `fdb_future_get_value()` to extract the value, and then destroy the `FDBFuture` with `fdb_future_destroy()`.

  See `fdb_future_get_value()` to see exactly how results are unpacked. If `key_name` is not present in the database, the result is not an error, but a zero for `*out_present` returned from that function.

  `key_name`
    A pointer to the name of the key to be looked up in the database. The value does not need to be NULL-terminated.
  `key_name_length`
    The length of the parameter specified by `key_name`.
  `snapshot`
    Non-zero if this is a snapshot read.

FDBFuture* `fdb_transaction_get_key`( FDBTransaction* transaction, uint8_t const* key_name, int key_name_length, fdb_bool_t or_equal, int offset, fdb_bool_t snapshot)

  Resolves a key selector against the keys in the database snapshot represented by `transaction`.

  Returns an `FDBFuture` which will be set to the key in the database matching the key selector. You must first wait for the `FDBFuture` to be ready, check for errors, call `fdb_future_get_key()` to extract the key, and then destroy the `FDBFuture` with `fdb_future_destroy()`.

  `key_name`, `key_name_length`, `or_equal`, `offset`
    The four components of a key selector.
  `snapshot`
    Non-zero if this is a snapshot read.

FDBFuture* `fdb_transaction_get_addresses_for_key`( FDBTransaction* transaction, uint8_t const* key_name, int key_name_length)

  Returns a list of public network addresses as strings, one for each of the storage servers responsible for storing `key_name` and its associated value.

  Returns an `FDBFuture` which will be set to an array of strings. You must first wait for the `FDBFuture` to be ready, check for errors, call `fdb_future_get_string_array()` to extract the string array, and then destroy the `FDBFuture` with `fdb_future_destroy()`.

  `key_name`
    A pointer to the name of the key whose location is to be queried.
  `key_name_length`
    The length of the parameter specified by `key_name`.

FDBFuture* `fdb_transaction_get_range`( FDBTransaction* transaction, uint8_t const* begin_key_name, int begin_key_name_length, fdb_bool_t begin_or_equal, int begin_offset, uint8_t const* end_key_name, int end_key_name_length, fdb_bool_t end_or_equal, int end_offset, int limit, int target_bytes, FDBStreamingMode mode, int iteration, fdb_bool_t snapshot, fdb_bool_t reverse)

  Reads all key-value pairs in the database snapshot represented by `transaction` (potentially limited by `limit`, `target_bytes`, or `mode`) which have a key lexicographically greater than or equal to the key resolved by the begin key selector and lexicographically less than the key resolved by the end key selector.

  Returns an `FDBFuture` which will be set to an `FDBKeyValue` array. You must first wait for the `FDBFuture` to be ready, check for errors, call `fdb_future_get_keyvalue_array()` to extract the key-value array, and then destroy the `FDBFuture` with `fdb_future_destroy()`.

  `begin_key_name`, `begin_key_name_length`, `begin_or_equal`, `begin_offset`
    The four components of a key selector describing the beginning of the range.
  `end_key_name`, `end_key_name_length`, `end_or_equal`, `end_offset`
    The four components of a key selector describing the end of the range.
  `limit`
    If non-zero, indicates the maximum number of key-value pairs to return. If this limit was reached before the end of the specified range, then the `*more` return of `fdb_future_get_keyvalue_array()` will be set to a non-zero value.
  `target_bytes`
    If non-zero, indicates a (soft) cap on the combined number of bytes of keys and values to return. If this limit was reached before the end of the specified range, then the `*more` return of `fdb_future_get_keyvalue_array()` will be set to a non-zero value.
  `mode`
    One of the `FDBStreamingMode` values indicating how the caller would like the data in the range returned.
  `iteration`
    If `mode` is `FDB_STREAMING_MODE_ITERATOR`, this parameter should start at 1 and be incremented by 1 for each successive call while reading this range. In all other cases it is ignored.
  `snapshot`
    Non-zero if this is a snapshot read.

  `reverse`

  > If non-zero, key-value pairs will be returned in reverse lexicographical order beginning at the end of the range.

`FDBStreamingMode`

  An enumeration of available streaming modes to be passed to `fdb_transaction_get_range()`.

  `FDB_STREAMING_MODE_ITERATOR`

  > The caller is implementing an iterator (most likely in a binding to a higher level language). The amount of data returned depends on the value of the `iteration` parameter to `fdb_transaction_get_range()`.

  `FDB_STREAMING_MODE_SMALL`

  > Data is returned in small batches (not much more expensive than reading individual key-value pairs).

  `FDB_STREAMING_MODE_MEDIUM`

  > Data is returned in batches between _SMALL and _LARGE.

  `FDB_STREAMING_MODE_LARGE`

  > Data is returned in batches large enough to be, in a high-concurrency environment, nearly as efficient as possible. If the caller does not need the entire range, some disk and network bandwidth may be wasted. The batch size may be still be too small to allow a single client to get high throughput from the database.

  `FDB_STREAMING_MODE_SERIAL`

  > Data is returned in batches large enough that an individual client can get reasonable read bandwidth from the database. If the caller does not need the entire range, considerable disk and network bandwidth may be wasted.

  `FDB_STREAMING_MODE_WANT_ALL`

  > The caller intends to consume the entire range and would like it all transferred as early as possible.

  `FDB_STREAMING_MODE_EXACT`

  > The caller has passed a specific row limit and wants that many rows delivered in a single batch.

void `fdb_transaction_set`( FDBTransaction* transaction, uint8_t const* key_name, int key_name_length, uint8_t const* value, int value_length)

  Modify the database snapshot represented by `transaction` to change the given key to have the given value. If the given key was not previously present in the database it is inserted.

  The modification affects the actual database only if `transaction` is later committed with `fdb_transaction_commit()`.

  `key_name`
    A pointer to the name of the key to be inserted into the database. The value does not need to be NULL-terminated.
  `key_name_length`
    The length of the parameter specified by `key_name`.
  `value`
    A pointer to the value to be inserted into the database. The value does not need to be NULL-terminated.
  `value_length`
    The length of the parameter specified by `value`.

void `fdb_transaction_clear`( FDBTransaction* transaction, uint8_t const* key_name, int key_name_length)

  Modify the database snapshot represented by `transaction` to remove the given key from the database. If the key was not previously present in the database, there is no effect.

  The modification affects the actual database only if `transaction` is later committed with `fdb_transaction_commit()`.

  `key_name`
    A pointer to the name of the key to be removed from the database. The value does not need to be NULL-terminated.
  `key_name_length`
    The length of the parameter specified by `key_name`.

void `fdb_transaction_clear_range`( FDBTransaction* transaction, uint8_t const* begin_key_name, int begin_key_name_length, uint8_t const* end_key_name, int end_key_name_length)

  Modify the database snapshot represented by `transaction` to remove all keys (if any) which are lexicographically greater than or equal to the given begin key and lexicographically less than the given end_key.

  The modification affects the actual database only if `transaction` is later committed with `fdb_transaction_commit()`.

  `begin_key_name`
    A pointer to the name of the key specifying the beginning of the range to clear. The value does not need to be NULL-terminated.
  `begin_key_name_length`
    The length of the parameter specified by `begin_key_name`.
  `end_key_name`
    A pointer to the name of the key specifying the end of the range to clear. The value does not need to be NULL-terminated.
  `end_key_name_length`
    The length of the parameter specified by `end_key_name_length`.

void `fdb_transaction_atomic_op`( FDBTransaction* transaction, uint8_t const* key_name, int key_name_length, uint8_t const* param, int param_length, FDBMutationType operationType)

  Modify the database snapshot represented by `transaction` to perform the operation indicated by `operationType` with operand `param` to the value stored by the given key.

  An atomic operation is a single database command that carries out several logical steps: reading the value of a key, performing a transformation on that value, and writing the result. Different atomic operations perform different transformations. Like other database operations, an atomic operation is used within a transaction; however, its use within a transaction will not cause the transaction to conflict.

  Atomic operations do not expose the current value of the key to the client but simply send the database the transformation to apply. In regard to conflict checking, an atomic operation is equivalent to a write without a read. It can only cause other transactions performing reads of the key to conflict.

  By combining these logical steps into a single, read-free operation, FoundationDB can guarantee that the transaction will not conflict due to the operation. This makes atomic operations ideal for operating on keys that are frequently modified. A common example is the use of a key-value pair as a counter.

  Warning

  If a transaction uses both an atomic operation and a serializable read on the same key, the benefits of using the atomic operation (for both conflict checking and performance) are lost.

  The modification affects the actual database only if `transaction` is later committed with `fdb_transaction_commit()`.

  `key_name`
    A pointer to the name of the key whose value is to be mutated.
  `key_name_length`
    The length of the parameter specified by `key_name`.
  `param`
    A pointer to the parameter with which the atomic operation will mutate the value associated with `key_name`.
  `param_length`
    The length of the parameter specified by `param`.
  `operation_type`
    One of the `FDBMutationType` values indicating which operation should be performed.

`FDBMutationType`

  An enumeration of available opcodes to be passed to `fdb_transaction_atomic_op()`

  `FDB_MUTATION_TYPE_ADD`

  Performs an addition of little-endian integers. If the existing value in the database is not present or shorter than `param`, it is first extended to the length of `param` with zero bytes. If `param` is shorter than the existing value in the database, the existing value is truncated to match the length of `param`.

  The integers to be added must be stored in a little-endian representation. They can be signed in two’s complement representation or unsigned. You can add to an integer at a known offset in the value by prepending the appropriate number of zero bytes to `param` and padding with zero bytes to match the length of the value. However, this offset technique requires that you know the addition will not cause the integer field within the value to overflow.

  `FDB_MUTATION_TYPE_AND`

  Performs a bitwise “and” operation. If the existing value in the database is not present, then `param` is stored in the database. If the existing value in the database is shorter than `param`, it is first extended to the length of `param` with zero bytes. If `param` is shorter than the existing value in the database, the existing value is truncated to match the length of `param`.

  `FDB_MUTATION_TYPE_OR`

  Performs a bitwise “or” operation. If the existing value in the database is not present or shorter than `param`, it is first extended to the length of `param` with zero bytes. If `param` is shorter than the existing value in the database, the existing value is truncated to match the length of `param`.

  `FDB_MUTATION_TYPE_XOR`

  Performs a bitwise “xor” operation. If the existing value in the database is not present or shorter than `param`, it is first extended to the length of `param` with zero bytes. If `param` is shorter than the existing value in the database, the existing value is truncated to match the length of `param`.

  `FDB_MUTATION_TYPE_MAX`

  Sets the value in the database to the larger of the existing value and `param`. If the existing value in the database is not present or shorter than `param`, it is first extended to the length of `param` with zero bytes. If `param` is shorter than the existing value in the database, the existing value is truncated to match the length of `param`.

  Both the existing value and `param` are treated as unsigned integers. (This differs from the behavior of atomic addition.)

  `FDB_MUTATION_TYPE_BYTE_MAX`

  Performs lexicographic comparison of byte strings. If the existing value in the database is not present, then `param` is stored. Otherwise the larger of the two values is then stored in the database.

  `FDB_MUTATION_TYPE_MIN`

  Sets the value in the database to the smaller of the existing value and `param`. If the existing value in the database is not present, then `param` is stored in the database. If the existing value in the database is shorter than `param`, it is first extended to the length of `param` with zero bytes. If `param` is shorter than the existing value in the database, the existing value is truncated to match the length of `param`.

  Both the existing value and `param` are treated as unsigned integers. (This differs from the behavior of atomic addition.)

  `FDB_MUTATION_TYPE_BYTE_MIN`

  Performs lexicographic comparison of byte strings. If the existing value in the database is not present, then `param` is stored. Otherwise the smaller of the two values is then stored in the database.

  `FDB_MUTATION_TYPE_SET_VERSIONSTAMPED_KEY`

  Transforms `key` using a versionstamp for the transaction. This key must be at least 12 bytes long. The final 2 bytes will be interpreted as a 16-bit little-endian integer denoting an index into the key at which to perform the transformation, and then trimmed off the key. The 10 bytes in the key beginning at the index will be overwritten with the versionstamp. If the index plus 10 bytes points past the end of the key, the result will be an error. Sets the transformed key in the database to `param`.

  A versionstamp is a 10 byte, unique, monotonically (but not sequentially) increasing value for each committed transaction. The first 8 bytes are the committed version of the database. The last 2 bytes are monotonic in the serialization order for transactions.

  A transaction is not permitted to read any transformed key or value previously set within that transaction, and an attempt to do so will result in an error.

  This operation is not compatible with the READ_YOUR_WRITES_DISABLE `transaction option` and will generate an error if used with it.

  Warning

  At this time, versionstamped keys are not compatible with the Tuple layer except in Java and Python. Note that this implies versionstamped keys may not be used with the Subspace and Directory layers except in those languages.

  `FDB_MUTATION_TYPE_SET_VERSIONSTAMPED_VALUE`

  Transforms `param` using a versionstamp for the transaction. This parameter must be at least 10 bytes long, and the first 10 bytes will be overwritten with the versionstamp. Sets `key` in the database to the transformed parameter.

  A versionstamp is a 10 byte, unique, monotonically (but not sequentially) increasing value for each committed transaction. The first 8 bytes are the committed version of the database. The last 2 bytes are monotonic in the serialization order for transactions.

  A transaction is not permitted to read any transformed key or value previously set within that transaction, and an attempt to do so will result in an error.

  Warning

  At this time, versionstamped values are not compatible with the Tuple layer.

FDBFuture* `fdb_transaction_commit`( FDBTransaction* transaction)

  Attempts to commit the sets and clears previously applied to the database snapshot represented by `transaction` to the actual database. The commit may or may not succeed – in particular, if a conflicting transaction previously committed, then the commit must fail in order to preserve transactional isolation. If the commit does succeed, the transaction is durably committed to the database and all subsequently started transactions will observe its effects.

  It is not necessary to commit a read-only transaction – you can simply call `fdb_transaction_destroy()`.

  Returns an `FDBFuture` representing an empty value. You must first wait for the `FDBFuture` to be ready, check for errors, and then destroy the `FDBFuture` with `fdb_future_destroy()`.

  Callers will usually want to retry a transaction if the commit or a prior `fdb_transaction_get_*()` returns a retryable error (see `fdb_transaction_on_error()`).

  As with other client/server databases, in some failure scenarios a client may be unable to determine whether a transaction succeeded. In these cases, `fdb_transaction_commit()` will return a commit_unknown_result error. The `fdb_transaction_on_error()` function treats this error as retryable, so retry loops that don’t check for commit_unknown_result could execute the transaction twice. In these cases, you must consider the idempotence of the transaction. For more information, see Transactions with unknown results.

  Normally, commit will wait for outstanding reads to return. However, if those reads were snapshot reads or the transaction option for disabling “read-your-writes” has been invoked, any outstanding reads will immediately return errors.

fdb_error_t `fdb_transaction_get_committed_version`( FDBTransaction* transaction, int64_t* out_version)

  Retrieves the database version number at which a given transaction was committed. `fdb_transaction_commit()` must have been called on `transaction` and the resulting future must be ready and not an error before this function is called, or the behavior is undefined. Read-only transactions do not modify the database when committed and will have a committed version of -1. Keep in mind that a transaction which reads keys and then sets them to their current values may be optimized to a read-only transaction.

  Note that database versions are not necessarily unique to a given transaction and so cannot be used to determine in what order two transactions completed. The only use for this function is to manually enforce causal consistency when calling `fdb_transaction_set_read_version()` on another subsequent transaction.

  Most applications will not call this function.

FDBFuture* `fdb_transaction_get_versionstamp`( FDBTransaction* transaction)

  Returns an `FDBFuture` which will be set to the versionstamp which was used by any versionstamp operations in this transaction. You must first wait for the `FDBFuture` to be ready, check for errors, call `fdb_future_get_key()` to extract the key, and then destroy the `FDBFuture` with `fdb_future_destroy()`.

  The future will be ready only after the successful completion of a call to `fdb_transaction_commit()` on this Transaction. Read-only transactions do not modify the database when committed and will result in the future completing with an error. Keep in mind that a transaction which reads keys and then sets them to their current values may be optimized to a read-only transaction.

  Most applications will not call this function.

FDBFuture* `fdb_transaction_watch`( FDBTransaction* transaction, uint8_t const* key_name, int key_name_length)

  A watch’s behavior is relative to the transaction that created it. A watch will report a change in relation to the key’s value as readable by that transaction. The initial value used for comparison is either that of the transaction’s read version or the value as modified by the transaction itself prior to the creation of the watch. If the value changes and then changes back to its initial value, the watch might not report the change.

  Until the transaction that created it has been committed, a watch will not report changes made by other transactions. In contrast, a watch will immediately report changes made by the transaction itself. Watches cannot be created if the transaction has set the READ_YOUR_WRITES_DISABLE `transaction option`, and an attempt to do so will return an watches_disabled error.

  If the transaction used to create a watch encounters an error during commit, then the watch will be set with that error. A transaction whose commit result is unknown will set all of its watches with the commit_unknown_result error. If an uncommitted transaction is reset or destroyed, then any watches it created will be set with the transaction_cancelled error.

  Returns an `FDBFuture` representing an empty value that will be set once the watch has detected a change to the value at the specified key. You must first wait for the `FDBFuture` to be ready, check for errors, and then destroy the `FDBFuture` with `fdb_future_destroy()`.

  By default, each database connection can have no more than 10,000 watches that have not yet reported a change. When this number is exceeded, an attempt to create a watch will return a too_many_watches error. This limit can be changed using the MAX_WATCHES `database option`. Because a watch outlives the transaction that creates it, any watch that is no longer needed should be cancelled by calling `fdb_future_cancel()` on its returned future.

  `key_name`
    A pointer to the name of the key to watch. The value does not need to be NULL-terminated.
  `key_name_length`
    The length of the parameter specified by `key_name`.

FDBFuture* `fdb_transaction_on_error`( FDBTransaction* transaction, fdb_error_t error)

  Implements the recommended retry and backoff behavior for a transaction. This function knows which of the error codes generated by other `fdb_transaction_*()` functions represent temporary error conditions and which represent application errors that should be handled by the application. It also implements an exponential backoff strategy to avoid swamping the database cluster with excessive retries when there is a high level of conflict between transactions.

  On receiving any type of error from an `fdb_transaction_*()` function, the application should:

  1. Call `fdb_transaction_on_error()` with the returned `fdb_error_t` code.
  2. Wait for the resulting future to be ready.
  3. If the resulting future is itself an error, destroy the future and FDBTransaction and report the error in an appropriate way.
  4. If the resulting future is not an error, destroy the future and restart the application code that performs the transaction. The transaction itself will have already been reset to its initial state, but should not be destroyed and re-created because state used by `fdb_transaction_on_error()` to implement its backoff strategy and state related to timeouts and retry limits is stored there.

  Returns an `FDBFuture` representing an empty value. You must first wait for the `FDBFuture` to be ready, check for errors, and then destroy the `FDBFuture` with `fdb_future_destroy()`.

void `fdb_transaction_reset`( FDBTransaction* transaction)

  Reset `transaction` to its initial state. This is similar to calling `fdb_transaction_destroy()` followed by `fdb_database_create_transaction()`. It is not necessary to call `fdb_transaction_reset()` when handling an error with `fdb_transaction_on_error()` since the transaction has already been reset.

void `fdb_transaction_cancel`( FDBTransaction* transaction)

  Cancels the transaction. All pending or future uses of the transaction will return a transaction_cancelled error. The transaction can be used again after it is `reset`.

  Warning

  Be careful if you are using `fdb_transaction_reset()` and `fdb_transaction_cancel()` concurrently with the same transaction. Since they negate each other’s effects, a race condition between these calls will leave the transaction in an unknown state.

  Warning

  If your program attempts to cancel a transaction after `fdb_transaction_commit()` has been called but before it returns, unpredictable behavior will result. While it is guaranteed that the transaction will eventually end up in a cancelled state, the commit may or may not occur. Moreover, even if the call to `fdb_transaction_commit()` appears to return a transaction_cancelled error, the commit may have occurred or may occur in the future. This can make it more difficult to reason about the order in which transactions occur.

fdb_error_t `fdb_transaction_add_conflict_range`( FDBTransaction* transaction, uint8_t const* begin_key_name, int begin_key_name_length, uint8_t const* end_key_name, int end_key_name_length, FDBConflictRangeType type)

  Adds a conflict range to a transaction without performing the associated read or write.

  Note

  Most applications will use the serializable isolation that transactions provide by default and will not need to manipulate conflict ranges.

  `begin_key_name`
    A pointer to the name of the key specifying the beginning of the conflict range. The value does not need to be NULL-terminated.
  `begin_key_name_length`
    The length of the parameter specified by `begin_key_name`.
  `end_key_name`
    A pointer to the name of the key specifying the end of the conflict range. The value does not need to be NULL-terminated.
  `end_key_name_length`
    The length of the parameter specified by `end_key_name_length`.
  `type`
    One of the `FDBConflictRangeType` values indicating what type of conflict range is being set.

`FDBConflictRangeType`

  An enumeration of available conflict range types to be passed to `fdb_transaction_add_conflict_range()`.

  `FDB_CONFLICT_RANGE_TYPE_READ`

  Adds a range of keys to the transaction’s read conflict ranges as if you had read the range. As a result, other transactions that write a key in this range could cause the transaction to fail with a conflict.

  `FDB_CONFLICT_RANGE_TYPE_WRITE`

  Adds a range of keys to the transaction’s write conflict ranges as if you had cleared the range. As a result, other transactions that concurrently read a key in this range could fail with a conflict.

### Snapshot reads

Snapshot reads selectively relax FoundationDB’s isolation property, reducing conflicts but making it harder to reason about concurrency.

By default, FoundationDB transactions guarantee serializable isolation, resulting in a state that is as if transactions were executed one at a time, even if they were executed concurrently. Serializability has little performance cost when there are few conflicts but can be expensive when there are many. FoundationDB therefore also permits individual reads within a transaction to be done as snapshot reads.

Snapshot reads differ from ordinary (serializable) reads by permitting the values they read to be modified by concurrent transactions, whereas serializable reads cause conflicts in that case. Like serializable reads, snapshot reads see the effects of prior writes in the same transaction. For more information on the use of snapshot reads, see Snapshot reads.

In the C API, snapshot reads are performed by passing a non-zero value to the `snapshot` parameter of any of `fdb_transaction_get_*` (see for example `fdb_transaction_get()`). Snapshot reads also interact with transaction commit a little differently than normal reads. If a snapshot read is outstanding when transaction commit is called that read will immediately return an error. (Normally, transaction commit will wait until outstanding reads return before committing.)

## Key selectors

FoundationDB’s lexicographically ordered data model permits finding keys based on their order (for example, finding the first key in the database greater than a given key). Key selectors represent a description of a key in the database that could be resolved to an actual key by `fdb_transaction_get_key()` or used directly as the beginning or end of a range in `fdb_transaction_get_range()`.

For more about how key selectors work, see Key selectors.

In the FoundationDB C API, key selectors are not represented by a structure of any kind, but are instead expressed as sequential parameters to `fdb_transaction_get_key()` and `fdb_transaction_get_range()`. For convenience, the most common key selectors are available as C macros that expand to the appropriate parameters.

`FDB_KEYSEL_LAST_LESS_THAN`(key_name, key_name_length)

`FDB_KEYSEL_LAST_LESS_OR_EQUAL`(key_name, key_name_length)

`FDB_KEYSEL_FIRST_GREATER_THAN`(key_name, key_name_length)

`FDB_KEYSEL_FIRST_GREATER_OR_EQUAL`(key_name, key_name_length)

To use one of these macros, simply replace the four parameters in the function with one of `FDB_KEYSEL_*()`:

    future = fdb_transaction_get_key(transaction, "key", 3, 0, 2, 0);

could instead be written as:

    future = fdb_transaction_get_key(transaction, FDB_KEYSEL_FIRST_GREATER_THAN("key", 3)+1, 0);

## Miscellaneous

`fdb_bool_t`

  An integer type representing a boolean. A value of 0 is false and non-zero is true.

`fdb_error_t`

  An integer type representing an error. A value of 0 is success and non-zero is an error.

const char* `fdb_get_error`( fdb_error_t code)

  Returns a (somewhat) human-readable English message from an error code. The return value is a statically allocated null-terminated string that must not be freed by the caller.

fdb_bool_t `fdb_error_predicate`(int predicate_test, fdb_error_t code)

  Evaluates a predicate against an error code. The predicate to run should be one of the codes listed by the `FDBErrorPredicate` enum defined within `fdb_c_options.g.h`. Sample predicates include `FDB_ERROR_PREDICATE_RETRYABLE`, which can be used to determine whether the error with the given code is a retryable error or not.