OpenDAL C Binding
The C binding for Apache OpenDAL
OpenDAL C Binding (WIP)


A simple read and write example

#include "assert.h"
#include "opendal.h"
#include "stdio.h"
int main()
/* Initialize a operator for "memory" backend, with no options */
assert(op.ptr != NULL);
/* Prepare some data to be written */
opendal_bytes data = {
.data = (uint8_t*)"this_string_length_is_24",
.len = 24,
/* Write this into path "/testpath" */
opendal_code code = opendal_operator_blocking_write(op, "/testpath", data);
assert(code == OPENDAL_OK);
/* We can read it out, make sure the data is the same */
opendal_bytes* read_bytes =;
assert(r.code == OPENDAL_OK);
assert(read_bytes->len == 24);
/* Lets print it out */
for (int i = 0; i < 24; ++i) {
printf("%c", read_bytes->data[i]);
/* the opendal_bytes read is heap allocated, please free it */
/* the operator_ptr is also heap allocated */
const struct opendal_operator_ptr * opendal_operator_new(const char *scheme, const struct opendal_operator_options *options)
Construct an operator based on scheme and options
void opendal_operator_free(const struct opendal_operator_ptr *op)
Free the heap-allocated operator pointed by opendal_operator_ptr.
The error code for all opendal APIs in C binding.
Definition: opendal.h:33
Definition: opendal.h:37
enum opendal_code opendal_operator_blocking_write(const struct opendal_operator_ptr *ptr, const char *path, struct opendal_bytes bytes)
Blockingly write raw bytes to path.
struct opendal_result_read opendal_operator_blocking_read(const struct opendal_operator_ptr *ptr, const char *path)
Blockingly read the data from path.
void opendal_bytes_free(struct opendal_bytes *ptr)
Frees the heap memory used by the opendal_bytes.
opendal_bytes carries raw-bytes with its length
Definition: opendal.h:260
uintptr_t len
Definition: opendal.h:268
const uint8_t * data
Definition: opendal.h:264
Used to access almost all OpenDAL APIs. It represents a operator that provides the unified interfaces...
Definition: opendal.h:225
const struct BlockingOperator * ptr
Definition: opendal.h:230
The result type returned by opendal's read operation.
Definition: opendal.h:279
enum opendal_code code
Definition: opendal.h:287
struct opendal_bytes * data
Definition: opendal.h:283

For more examples, please refer to ./examples


To build OpenDAL C binding, the following is all you need:

  • A C++ compiler that supports c++14, e.g. clang++ and g++
  • To format the code, you need to install clang-format
    • The opendal.h is not formatted by hands when you contribute, please do not format the file. Use make format only.
    • If your contribution is related to the files under ./tests, you may format it before submitting your pull request. But notice that different versions of clang-format may format the files differently.
  • GTest(Google Test) need to be installed to build the BDD (Behavior Driven Development) tests. To see how to build, check here.
  • (optional) Doxygen need to be installed to generate documentations.

For Ubuntu and Debian:

# install C/C++ toolchain
sudo apt install -y build-essential
# install clang-format
sudo apt install clang-format
# install and build GTest library under /usr/lib and softlink to /usr/local/lib
sudo apt-get install libgtest-dev
# install CMake
sudo apt-get install cmake
# install Rust
curl --proto '=https' --tlsv1.2 -sSf | sh
# If you run the tests, install additional components
# install Valgrind
sudo apt-get install Valgrind
# install GTest
cd /usr/src/gtest
sudo cmake CMakeLists.txt
sudo make
sudo cp lib/*.a /usr/lib
sudo ln -s /usr/lib/libgtest.a /usr/local/lib/libgtest.a
sudo ln -s /usr/lib/libgtest_main.a /usr/local/lib/libgtest_main.a


  • To build the library and header file.
make build
  • The header file opendal.h is under ./include
  • The library is under ../../target/debug after building.

To clean the build results.

make clean
  • To build and run the tests. (Note that you need to install Valgrind and GTest)
make test
  • To build the examples
make examples


The documentation index page source is under ./docs/doxygen/html/index.html. If you want to build the documentations yourself, you could use

# this requires you to install doxygen
make doc


Apache v2.0