LIBCBOR(3)

📦

version 0.13.0 · 3 versions

0.13.0 · fedora 44 (latest)
0.11.0 · opensuse-leap 16.0
0.12.0 · fedora 43

🦋 libcbor — the `LIBCBOR(3)` manual page, but make it make sense 🦋

okay so bestie, pull up a chair, grab a strawberry 🍓, because we're about to get into libcbor and honestly? it's giving iconic.

📛 NAME 📛

libcbor — this is the libcbor documentation. yeah. that's the name. slay.

so like, this is the docs for version 0.13.0, updated on Jan 16, 2026 ✨

Git repo, if you wanna go lurk: <https://github.com/PJK/libcbor>

🌈 OVERVIEW 🌈

libcbor is a C library for parsing and generating CBOR <https://www.rfc-editor.org/info/std94> — and CBOR is the general-purpose, schema-less, binary data format. no schema, no problem, we just vibe 💅

✨ Main features ✨

Complete IETF RFC 8949 (STD 94) <https://www.rfc-editor.org/info/std94> conformance [1] 👑
Robust C99 implementation
Layered architecture offers both control and convenience
Flexible memory management
No shared global state — threading friendly [2] 🧵
Proper handling of UTF-8
Full support for streams & incremental processing
Extensive documentation and test suite
No runtime dependencies, small footprint 🦋

[1] See IETF standard conformance. [2] With the exception of custom memory allocators (see Memory management and reference counting).

📚 CONTENTS 📚

🎀 Getting started 🎀

pre-built Linux packages are literally right there in most mainstream distributions, no cap:

Ubuntu, Debian, etc.:

apt-get install libcbor-dev

Fedora, openSUSE, etc.:

yum install libcbor-devel

OS X girlies can use Homebrew <http://brew.sh/>:

brew install libcbor

For other platforms, you will need to compile it from source. yeah. from scratch. it's fine. you got this. 💪

🛠️ Building & installing libcbor 🛠️

Prerequisites, aka the vibe check before you start:

C99 compiler
CMake <http://cmake.org/> 2.8 or newer (might also be called cmakesetup, cmake-gui or ccmake depending on the installed version and system) 👀
C build system CMake can target (make, Apple Xcode, MinGW, ...)

⚙️ Configuration options ⚙️

a handful of configuration flags can be passed to cmake. here's the full rundown — libcbor compile-time directives plus several important generic flags:

CMAKE_C_COMPILER — C compiler to use. Default: cc. Possible values: gcc, clang, clang-3.5, ...
CMAKE_INSTALL_PREFIX — Installation prefix. Default: System-dependent. Possible values: /usr/local/lib, ...
CMAKE_INTERPROCEDURAL_OPTIMIZATION — Enable LTO (if supported). Default: System-dependent. Possible values: ON, OFF
BUILD_SHARED_LIBS — Build as a shared library. Default: OFF. Possible values: ON, OFF
HUGE_FUZZ — Fuzz test with 8GB of data. Default: OFF. Possible values: ON, OFF
SANE_MALLOC — Assume malloc will refuse unreasonable allocations. Default: OFF. Possible values: ON, OFF
COVERAGE — Generate test coverage instrumentation. Default: OFF. Possible values: ON, OFF
WITH_TESTS — Build unit tests (see Development). Default: OFF. Possible values: ON, OFF

and the following configuration options will also be defined as macros [1] in <cbor/common.h> and can therefore be used in client code — so like, you can actually touch them from your own code, bestie:

CBOR_PRETTY_PRINTER — Include a pretty-printing routine. Default: ON. Possible values: ON, OFF
CBOR_BUFFER_GROWTH — Factor for buffer growth & shrinking. Default: 2. Possible values: Decimals > 1

[1] ON & OFF will be translated to 1 and 0 using cmakedefine <https://cmake.org/cmake/help/v3.2/command/configure_file.html?highlight=cmakedefine>. If you want to pass other custom configuration options, please refer to <http://www.cmake.org/Wiki/CMake_Useful_Variables>.

Note: When CMAKE_INTERPROCEDURAL_OPTIMIZATION is enabled, the generated static library (libcbor.a) should be used with an LTO-enabled linker downstream. On LLVM toolchains without bitcode embedding (-fembed-bitcode), the archive will contain LLVM IR only and linking without LTO will not work <https://github.com/PJK/libcbor/issues/372>. 😭 do not skip this one.

Warning: CBOR_CUSTOM_ALLOC has been removed <https://github.com/PJK/libcbor/pull/237>. Custom allocators (historically a controlled by a build flag) are always enabled. gone but never forgotten 🕊️

🧱 Building using make 🧱

CMake will generate a Makefile and other configuration files for the build. as a rule of thumb, you should configure the build outside of the source tree in order to keep different configurations isolated. if you are unsure where to execute the build, just use a temporary directory:

cd $(mktemp -d /tmp/cbor_build.XXXX)

Now, assuming you are in the directory where you want to build, build libcbor as a static library:

cmake -DCMAKE_BUILD_TYPE=Release path_to_libcbor_dir
make cbor

... or as a dynamic library:

cmake -DCMAKE_BUILD_TYPE=Release  -DBUILD_SHARED_LIBS=ON path_to_libcbor_dir
make cbor

To install locally:

make install

Root permissions are required on most systems when using the default installation prefix. 🔐

🌍 Portability 🌍

libcbor is highly portable and works on both little- and big-endian systems regardless of the operating system. after building on an exotic platform, you might wish to verify the result by running the test suite. if you encounter any problems, please report them to the issue tracker <https://github.com/PJK/libcbor/issues>. they wanna hear about it fr fr.

libcbor is known to successfully work on ARM Android devices. cross-compilation is possible with arm-linux-gnueabi-gcc. 🤖

🔗 Linking with libcbor 🔗

If you include and linker paths include the directories to which libcbor has been installed, compiling programs that uses libcbor requires no extra considerations. zero. none. it just works ✨

You can verify that everything has been set up properly by creating a file with the following contents:

#include <cbor.h>
#include <stdio.h>

int main(int argc, char * argv[])
{
    printf("Hello from libcbor %s\n", CBOR_VERSION);
}

and compiling it:

cc hello_cbor.c -lcbor -o hello_cbor

and that's just the beginning bestie, there is so much more coming 👀 keep scrolling 💜

Ok so — libcbor also comes with pkg-config support 🎀 (yes, the fancy freedesktop one: https://wiki.freedesktop.org/www/Software/pkg-config/). And if you installed libcbor with a custom prefix and your compiler is being dramatic about where the headers live, bestie, pkg-config will just resolve the headers and objects for you 💅

cc $(pkg-config --cflags libcbor) hello_cbor.c $(pkg-config --libs libcbor) -o hello_cbor

✨ A note on linkage ✨

Real talk: libcbor is primarily intended to be linked statically. That's the plan, that's the design, that's the whole moment 👑

The shared library versioning scheme generally follows SemVer (https://semver.org/), but — and this is the messy part — it's irregular for the 0.X.Y development branch, for historical reasons. 🙈

The following version identifiers are used as a part of the SONAME (Linux) or the dylib "Compatibility version" (OS X) (see https://developer.apple.com/library/archive/documentation/DeveloperTools/Conceptual/DynamicLibraries/100-Articles/CreatingDynamicLibraries.html):

0.Y for the 0.Y.Z branch. Patches are backwards compatible, but minor releases are generally not and require re-compilation of any dependent code 😭
X for the X.Y.Z stable versions starting 1.X.Y. All minor releases of the major version are backwards compatible 🫶

⚠️ Warning: releases up to and including v0.6.0 may export a misleading .so/.dylib version number (https://github.com/PJK/libcbor/issues/52). Not us being shady, just history being history.

🛠️ TROUBLESHOOTING 🛠️

cbor.h not found — the headers directory is probably not in your include path 😤 First, verify the installation location by checking the installation log. If you used make, it'll look something like

...
-- Installing: /usr/local/include/cbor
-- Installing: /usr/local/include/cbor/callbacks.h
-- Installing: /usr/local/include/cbor/encoding.h
...

Make sure that CMAKE_INSTALL_PREFIX (if you provided it) was correct. Including the path during compilation should suffice, e.g.:

cc -I/usr/local/include hello_cbor.c -lcbor -o hello_cbor

cannot find -lcbor during linking — most likely the same problem as before, bestie 🫠 Include the installation directory in the linker shared path using -R, e.g.:

cc -Wl,-rpath,/usr/local/lib -lcbor -o hello_cbor

shared library missing during execution — verify the linkage using ldd, otool, or similar, and adjust the compilation directives accordingly:

⇒  ldd hello_cbor
    linux-vdso.so.1 =>  (0x00007ffe85585000)
    libcbor.so => /usr/local/lib/libcbor.so (0x00007f9af69da000)
    libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f9af65eb000)
    /lib64/ld-linux-x86-64.so.2 (0x00007f9af6be9000)

compilation failed — if your compiler supports C99 yet the compilation has failed, please report the issue to the issue tracker (https://github.com/PJK/libcbor/issues) 🙏

🌸 TUTORIAL 🌸

libcbor is a C library to encode, decode, and manipulate CBOR data. It is to CBOR to what cJSON (https://github.com/DaveGamble/cJSON) is to JSON — like, that's the energy ✨

We assume you are already familiar with the CBOR standard. If not… we recommend cbor.io (http://cbor.io/) 💖

🌈 Where to start 🌈

Skim through the Crash course section below 👇
Examples of how to read, write, manipulate, and translate data to and from JSON using libcbor are in the examples directory (https://github.com/PJK/libcbor/tree/master/examples) 🍓
The API documentation is a complete reference of libcbor 📚

🦋 Crash course 🦋

💜 CBOR data objects are `cbor_item_t` 💜

void item_examples() {
  // A cbor_item_t can contain any CBOR data type
  cbor_item_t* float_item = cbor_build_float4(3.14f);
  cbor_item_t* string_item = cbor_build_string("Hello World!");
  cbor_item_t* array_item = cbor_new_indefinite_array();

  // They can be inspected
  assert(cbor_is_float(float_item));
  assert(cbor_typeof(string_item) == CBOR_TYPE_STRING);
  assert(cbor_array_is_indefinite(array_item));
  assert(cbor_array_size(array_item) == 0);

  // The data can be accessed
  assert(cbor_float_get_float4(float_item) == 3.14f);
  assert(memcmp(cbor_string_handle(string_item), "Hello World!",
                cbor_string_length(string_item)) == 0);

  // And they can be modified
  assert(cbor_array_push(array_item, float_item));
  assert(cbor_array_push(array_item, string_item));
  assert(cbor_array_size(array_item) == 2);

  // At the end of their lifetime, items must be freed
  cbor_decref(&float_item);
  cbor_decref(&string_item);
  cbor_decref(&array_item);
}

🧚 Objects can be serialized and deserialized 🧚

void encode_decode() {
  cbor_item_t* item = cbor_build_uint8(42);

  // Serialize the item to a buffer (it will be allocated by libcbor)
  unsigned char* buffer;
  size_t buffer_size;
  cbor_serialize_alloc(item, &buffer, &buffer_size);
  assert(buffer_size == 2);
  assert(buffer[0] == 0x18);  // Encoding byte for uint8
  assert(buffer[1] == 42);    // The value itself

  // And deserialize bytes back to an item
  struct cbor_load_result result;
  cbor_item_t* decoded_item = cbor_load(buffer, buffer_size, &result);
  assert(result.error.code == CBOR_ERR_NONE);
  assert(cbor_isa_uint(decoded_item));
  assert(cbor_get_uint8(decoded_item) == 42);

  // Free the allocated buffer and items
  free(buffer);
  cbor_decref(&decoded_item);
  cbor_decref(&item);
}

💅 Reference counting 💅

void reference_counting() {
  // cbor_item_t is a reference counted pointer under the hood
  cbor_item_t* item = cbor_build_uint8(42);

  // Reference count starts at 1
  assert(cbor_refcount(item) == 1);

  // Most operations have reference semantics
  cbor_item_t* array_item = cbor_new_definite_array(1);
  assert(cbor_array_push(array_item, item));
  assert(cbor_refcount(item) == 2);  // item and array_item reference it
  cbor_item_t* first_array_element = cbor_array_get(array_item, 0);
  assert(first_array_element == item);  // same item under the hood
  assert(cbor_refcount(item) ==
         3);  // and now first_array_element also points to it

  // To release the reference, use cbor_decref
  cbor_decref(&first_array_element);

  // When reference count reaches 0, the item is freed
  assert(cbor_refcount(array_item) == 1);
  cbor_decref(&array_item);
  assert(array_item == NULL);
  assert(cbor_refcount(item) == 1);

  // Be careful, loops leak memory!

  // Deep copy copies the whole item tree
  cbor_item_t* item_copy = cbor_copy(item);
  assert(cbor_refcount(item) == 1);
  assert(cbor_refcount(item_copy) == 1);
  assert(item_copy != item);
  cbor_decref(&item);
  cbor_decref(&item_copy);
}

🔥 Moving intermediate values 🔥

void moving_values() {
  {
    // Move the "42" into an array.
    cbor_item_t* array_item = cbor_new_definite_array(1);
    // The line below leaks memory!
    assert(cbor_array_push(array_item, cbor_build_uint8(42)));
    cbor_item_t* first_array_element = cbor_array_get(array_item, 0);
    assert(cbor_refcount(first_array_element) == 3);  // Should be 2!
    cbor_decref(&first_array_element);
    cbor_decref(&array_item);
    assert(cbor_refcount(first_array_element) == 1);  // Shouldn't exist!
    // Clean up
    cbor_decref(&first_array_element);
  }

  {
    // A correct way to move values is to decref them in the caller scope.
    cbor_item_t* array_item = cbor_new_definite_array(1);
    cbor_item_t* item = cbor_build_uint8(42);
    assert(cbor_array_push(array_item, item));
    assert(cbor_refcount(item) == 2);
    // "Give up" the item
    cbor_decref(&item);
    cbor_decref(&array_item);
    // item is a dangling pointer at this point
  }

  {
    // cbor_move avoids the need to decref and the dangling pointer
    cbor_item_t* array_item = cbor_new_definite_array(1);
    assert(cbor_array_push(array_item, cbor_move(cbor_build_uint8(42))));
    cbor_item_t* first_array_element = cbor_array_get(array_item, 0);
    assert(cbor_refcount(first_array_element) == 2);
    cbor_decref(&first_array_element);
    cbor_decref(&array_item);
  }
}

👑 Ownership 👑

// Refcount can be managed in conjunction with ownership
static cbor_item_t* global_item = NULL;

// This function takes shared ownership of the item
void borrow_item(cbor_item_t* item) {
  global_item = item;
  // Mark the extra reference
  cbor_incref(item);
}

void return_item() {
  cbor_decref(&global_item);
  global_item = NULL;
}

void reference_ownership() {
  cbor_item_t* item = cbor_build_uint8(42);

  // Lend the item
  borrow_item(item);
  assert(cbor_refcount(item) == 2);
  cbor_decref(&item);

  // Release the shared ownership. return_item will deallocate the item.
  return_item();
}

🌊 Streaming IO 🌊

See https://github.com/PJK/libcbor/blob/master/examples/streaming_array.c and https://github.com/PJK/libcbor/blob/master/examples/streaming_parser.c ✨

🎀 API 🎀

The data API is centered around cbor_item_t, a generic handle for any CBOR item 💖 There are functions to

create items,
set items' data,
parse serialized data into items,
manage, move, and link items together.

The single most important thing to keep in mind is: cbor_item_t is an opaque type and should only be manipulated using the appropriate functions! Think of it as an object 💅

The libcbor API closely follows the semantics outlined by the CBOR standard (https://tools.ietf.org/html/rfc7049). This part of the documentation provides a short overview of the CBOR constructs, as well as a general introduction to the libcbor API. The remaining reference can be found in the following files, structured by data types.

The API is designed to allow both very tight control & flexibility and general convenience with sane defaults. [1] For example, a client with very specific requirements (constrained environment, custom application protocol built on top of CBOR, etc.) may choose to take full control (and responsibility) of memory and data structures management by interacting directly with the decoder. Other clients might want to take control of specific aspects (streamed collections, hash maps storage), but leave other responsibilities to libcbor. More general clients might prefer to be abstracted away from all the aforementioned details and only be presented complete data structures ✨

libcbor provides

stateless encoders and decoders
encoding and decoding drivers, routines that coordinate encoding and decoding of complex structures
data structures to represent and transform CBOR structures
routines for building and manipulating these structures
utilities for inspection and debugging

✨ Types of items ✨

okay so every single cbor_item_t has a cbor_type attached to it, and those constants map one-to-one onto the types the CBOR standard defines 💖

enum cbor_type

Specifies the Major type of cbor_item_t.

Values:

CBOR_TYPE_UINT — 0 — positive integers 🔢
CBOR_TYPE_NEGINT — 1 — negative integers
CBOR_TYPE_BYTESTRING — 2 — byte strings 🧊
CBOR_TYPE_STRING — 3 — strings
CBOR_TYPE_ARRAY — 4 — arrays
CBOR_TYPE_MAP — 5 — maps 🗺️
CBOR_TYPE_TAG — 6 — tags 🏷️
CBOR_TYPE_FLOAT_CTRL — 7 — decimals and special values (true, false, nil, ...) 🎀

So to find out what type an item is, bestie, you literally just use this:

cbor_type cbor_typeof(const cbor_item_t *item)

item — the item
returns the type ✨

heads up! Please note the distinction between functions like cbor_isa_uint() and cbor_is_int(). The following functions work solely with the major type value.

🔍 Binary queries

Alternatively — and this is lowkey the easier route — there are functions to query each particular type 💅

Warning: Passing an invalid cbor_item_t reference to any of these functions results in undefined behavior. not me finding that out the hard way 😭

bool cbor_isa_uint(const cbor_item_t *item)