Skip to main content

Getting started

Build the library​

From bindings/c/:

mkdir -p build && cd build
cmake ..
make

This produces libopendal_c under ../../target/debug/. Link against it and include bindings/c/include/opendal.h.

Your first program​

This program builds a memory-backed operator, writes data, reads it back, inspects the metadata, and frees every heap-allocated value. It requires no credentials and no filesystem access.

#include <assert.h>
#include <stdio.h>
#include "opendal.h"

int main(void)
{
/* Build an operator for the "memory" service with no options. */
opendal_operator *op = NULL;
opendal_error *err = opendal_operator_new("memory", NULL, &op);
assert(err == NULL);
assert(op != NULL);

/* Write bytes to a path. */
const char *msg = "Hello, OpenDAL!";
opendal_bytes data = {
.data = (uint8_t *)msg,
.len = 15,
};
err = opendal_operator_write(op, "/hello.txt", &data);
assert(err == NULL);

/* Read the bytes back. */
opendal_bytes read_bytes = { 0 };
err = opendal_operator_read(op, "/hello.txt", &read_bytes);
assert(err == NULL);
assert(read_bytes.len == 15);
printf("%.*s\n", (int)read_bytes.len, read_bytes.data); /* Hello, OpenDAL! */
opendal_bytes_free(&read_bytes);

/* Stat the path to get metadata. */
opendal_metadata *meta = NULL;
err = opendal_operator_stat(op, "/hello.txt", &meta);
assert(err == NULL);
printf("size = %llu\n", (unsigned long long)opendal_metadata_content_length(meta));
opendal_metadata_free(meta);

/* Delete the file. */
opendal_error *del_err = opendal_operator_delete(op, "/hello.txt");
assert(del_err == NULL);

opendal_operator_free(op);
return 0;
}

Every fallible operation returns an opendal_error * (NULL on success) and writes any output value through a caller-provided output pointer. See Error handling below.

Point it at a real backend​

The only change is the scheme and the options you pass to opendal_operator_new. Operations stay identical across all services.

/* Filesystem operator rooted at /tmp/mydata */
opendal_operator_options *opts = opendal_operator_options_new();
opendal_operator_options_set(opts, "root", "/tmp/mydata");

opendal_operator *op = NULL;
opendal_error *err = opendal_operator_new("fs", opts, &op);
opendal_operator_options_free(opts); /* options are copied; free immediately */

assert(err == NULL && op != NULL);
/* ... same write/read/stat/delete calls ... */
opendal_operator_free(op);

For S3 or any other service, set the configuration keys documented on /services as key-value pairs via opendal_operator_options_set.

Error handling​

C has no exceptions. Every function that can fail returns an opendal_error * and initializes any output parameter on both success and failure:

  • NULL → success.
  • non-NULL → failure; inspect .code (an opendal_code enum) and .message (an opendal_bytes containing the error text, not NUL-terminated). Call opendal_error_free when done.
opendal_bytes data;
opendal_error *err = opendal_operator_read(op, "/no-such-file", &data);
if (err != NULL) {
/* .message is NOT NUL-terminated; use the length. */
fprintf(stderr, "error %d: %.*s\n",
err->code,
(int)err->message.len,
err->message.data);
opendal_error_free(err);
/* data is zero-initialized on failure */
}

Common error codes (from opendal_code):

CodeMeaning
OPENDAL_NOT_FOUNDPath does not exist
OPENDAL_PERMISSION_DENIEDInsufficient permissions
OPENDAL_ALREADY_EXISTSPath already exists
OPENDAL_UNSUPPORTEDOperation not supported by this service
OPENDAL_CONFIG_INVALIDOperator configuration is invalid

Memory ownership rules​

Every heap-allocated value returned by OpenDAL must be freed by the caller:

TypeFree with
opendal_operator *opendal_operator_free
opendal_bytes (field, not pointer)opendal_bytes_free (pass by address)
opendal_error *opendal_error_free
opendal_metadata *opendal_metadata_free
opendal_lister *opendal_lister_free
opendal_entry *opendal_entry_free
opendal_reader *opendal_reader_free
opendal_writer *opendal_writer_free
char * returned by metadata / entry / info accessorsopendal_string_free
opendal_operator_options *opendal_operator_options_free

Do not use free() directly on any of these; they are allocated inside the Rust runtime and must be released through the provided functions.