Your company here, and a link to your site. Click to find out more.

libcbor - Man Page

Name

libcbor — libcbor Documentation

Documentation for version 0.11.0, updated on Feb 04, 2024.

Overview

libcbor is a C library for parsing and generating CBOR, the general-purpose schema-less binary data format.

Main features

Complete IETF RFC 8949 (STD 94) 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)

Getting started

Pre-built Linux packages are available in most mainstream distributions

Ubuntu, Debian, etc.:

apt-get install libcbor-dev

Fedora, openSUSE, etc.:

yum install libcbor-devel

OS X users can use Homebrew:

brew install libcbor

For other platforms, you will need to compile it from source.

Building & installing libcbor

Prerequisites:

C99 compiler
CMake 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. The following table lists libcbor compile-time directives and several important generic flags.

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

The following configuration options will also be defined as macros [1] in <cbor/common.h> and can therefore be used in client code:

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

[1]

ON & OFF will be translated to 1 and 0 using cmakedefine.

If you want to pass other custom configuration options, please refer to http://www.cmake.org/Wiki/CMake_Useful_Variables.

WARNING:

CBOR_CUSTOM_ALLOC has been removed. Custom allocators (historically a controlled by a build flag) are always enabled.

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.

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.

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

libcbor also comes with pkg-config support. If you install libcbor with a custom prefix, you can use pkg-config to resolve the headers and objects:

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

A note on linkage

libcbor is primarily intended to be linked statically. The shared library versioning scheme generally follows SemVer, but is 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):

0.Y for the 0.Y.Z branch. Patches are backwards compatible, 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 release of the major version are backwards compatible.

WARNING:: Please note that releases up to and including v0.6.0 may export misleading .so/.dylib version number.

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 will 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 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. 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.

Usage & preliminaries

Version information

libcbor exports its version using three self-explanatory macros:

CBOR_MAJOR_VERSION
CBOR_MINOR_VERSION
CBOR_PATCH_VERSION

The CBOR_VERSION is a string concatenating these three identifiers into one (e.g. 0.2.0).

In order to simplify version comparisons, the version is also exported as

#define CBOR_HEX_VERSION ((CBOR_MAJOR_VERSION << 16) | (CBOR_MINOR_VERSION << 8) | CBOR_PATCH_VERSION)

Since macros are difficult to work with through FFIs, the same information is also available through three uint8_t constants, namely

cbor_major_version
cbor_minor_version
cbor_patch_version

Headers to include

The cbor.h header includes all the symbols. If, for any reason, you don't want to include all the exported symbols, feel free to use just some of the cbor/*.h headers:

cbor/arrays.h - Type 4 – Arrays
cbor/bytestrings.h - Type 2 – Byte strings
cbor/callbacks.h - Callbacks used for Streaming Decoding
cbor/common.h - Common utilities - always transitively included
cbor/data.h - Data types definitions - always transitively included
cbor/encoding.h - Streaming encoders for Streaming Encoding
cbor/floats_ctrls.h - Type 7 – Floats & control tokens
cbor/ints.h - Types 0 & 1 – Positive and negative integers
cbor/maps.h - Type 5 – Maps
cbor/serialization.h - High level serialization such as cbor_serialize()
cbor/streaming.h - Home of cbor_stream_decode()
cbor/strings.h - Type 3 – UTF-8 strings
cbor/tags.h - Type 6 – Semantic tags

Using libcbor

If you want to get more familiar with CBOR, we recommend the cbor.io website. Once you get the grasp of what is it CBOR does, the examples (located in the examples directory) should give you a good feel of the API. The API documentation should then provide with all the information you may need.

Creating and serializing items

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

int main(int argc, char * argv[])
{
    /* Preallocate the map structure */
    cbor_item_t * root = cbor_new_definite_map(2);
    /* Add the content */
    cbor_map_add(root, (struct cbor_pair) {
        .key = cbor_move(cbor_build_string("Is CBOR awesome?")),
        .value = cbor_move(cbor_build_bool(true))
    });
    cbor_map_add(root, (struct cbor_pair) {
        .key = cbor_move(cbor_build_uint8(42)),
        .value = cbor_move(cbor_build_string("Is the answer"))
    });
    /* Output: `buffer_size` bytes of data in the `buffer` */
    unsigned char * buffer;
    size_t buffer_size;
    cbor_serialize_alloc(root, &buffer, &buffer_size);

    fwrite(buffer, 1, buffer_size, stdout);
    free(buffer);

    fflush(stdout);
    cbor_decref(&root);
}

Reading serialized data

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

/*
 * Reads data from a file. Example usage:
 * $ ./examples/readfile examples/data/nested_array.cbor
 */

int main(int argc, char * argv[])
{
    FILE * f = fopen(argv[1], "rb");
    fseek(f, 0, SEEK_END);
    size_t length = (size_t)ftell(f);
    fseek(f, 0, SEEK_SET);
    unsigned char * buffer = malloc(length);
    fread(buffer, length, 1, f);

    /* Assuming `buffer` contains `info.st_size` bytes of input data */
    struct cbor_load_result result;
    cbor_item_t * item = cbor_load(buffer, length, &result);
    /* Pretty-print the result */
    cbor_describe(item, stdout);
    fflush(stdout);
    /* Deallocate the result */
    cbor_decref(&item);

    fclose(f);
}

Using the streaming parser

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

/*
 * Illustrates how one might skim through a map (which is assumed to have
 * string keys and values only), looking for the value of a specific key
 *
 * Use the examples/data/map.cbor input to test this.
 */

const char * key = "a secret key";
bool key_found = false;

void find_string(void * _ctx, cbor_data buffer, size_t len)
{
    if (key_found) {
        printf("Found the value: %*s\n", (int) len, buffer);
        key_found = false;
    } else if (len == strlen(key)) {
        key_found = (memcmp(key, buffer, len) == 0);
    }
}

int main(int argc, char * argv[])
{
    FILE * f = fopen(argv[1], "rb");
    fseek(f, 0, SEEK_END);
    size_t length = (size_t)ftell(f);
    fseek(f, 0, SEEK_SET);
    unsigned char * buffer = malloc(length);
    fread(buffer, length, 1, f);

    struct cbor_callbacks callbacks = cbor_empty_callbacks;
    struct cbor_decoder_result decode_result;
    size_t bytes_read = 0;
    callbacks.string = find_string;
    while (bytes_read < length) {
        decode_result = cbor_stream_decode(buffer + bytes_read,
                                           length - bytes_read,
                                           &callbacks, NULL);
        bytes_read += decode_result.read;
    }

    fclose(f);
}

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 links item 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 CBOR standard. This part of the documentation provides a short overview of the CBOR constructs, as well as a general introduction to the libcbor API. 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, 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 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

Every cbor_item_t has a cbor_type associated with it - these constants correspond to the types specified by the CBOR standard:

enum cbor_type

Specifies the Major type of cbor_item_t.

Values:

enumerator CBOR_TYPE_UINT: 0 - positive integers
enumerator CBOR_TYPE_NEGINT: 1 - negative integers
enumerator CBOR_TYPE_BYTESTRING: 2 - byte strings
enumerator CBOR_TYPE_STRING: 3 - strings
enumerator CBOR_TYPE_ARRAY: 4 - arrays
enumerator CBOR_TYPE_MAP: 5 - maps
enumerator CBOR_TYPE_TAG: 6 - tags
enumerator CBOR_TYPE_FLOAT_CTRL: 7 - decimals and special values (true, false, nil, ...)

To find out the type of an item, one can use

cbor_type cbor_typeof(const cbor_item_t *item)

Get the type of the item.

param item
return: The type

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, 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.

bool cbor_isa_uint(const cbor_item_t *item)