Decoding

libcbor provides two decoding interfaces:

	Default	Streaming
Function	cbor_load()	cbor_stream_decode()
Returns	A fully-built cbor_item_t tree.	Nothing. Fires a callback for each decoded value.
Callbacks	None. Results available after the call returns.	One callback per primitive, string chunk, or collection boundary (e.g. array_start, uint8, string_chunk).
Nesting	Handled by the library.	Caller’s responsibility. Nested structures (e.g. arrays containing maps) require the caller to maintain an explicit stack to track the current depth and accumulate children.
Memory	Allocates the cbor_item_t tree. Free with cbor_decref().	No library allocations.
Best for	Trusted or size-bounded inputs. General data manipulation and inspection. Simple use cases.	Large or unbounded inputs. Memory-constrained environments. Mapping to custom data structures. Known, restricted schemas.

cbor_load() is implemented on top of cbor_stream_decode() — it installs its own internal callbacks that build the cbor_item_t tree as events arrive.

This section covers the Default driver — cbor_load() and related routines that decode a complete CBOR input into a cbor_item_t tree in one call.

Warning

cbor_load allocates memory sized by lengths declared in the CBOR header before reading the corresponding data:

• Definite-length arrays and maps — storage for the declared element count.

• Definite-length strings and bytestrings — a buffer for the declared byte length.

All of these lengths are encoded as a 64-bit integer, so cbor_load may attempt an allocation of up to 2⁶⁴−1 bytes before any payload data is read. malloc will normally refuse such a request and cbor_load will return CBOR_ERR_MEMERROR, but on platforms with memory overcommit (Linux by default) the allocation may silently appear to succeed.

Mitigations:

• Install a capping allocator via cbor_set_allocs() to bound total memory consumption (see examples/capped_alloc.c for a self-contained example).

• Use the streaming decoder (Streaming Decoding), which gives the application full control over memory allocation for each decoded item.

cbor_item_t *cbor_load(cbor_data source, size_t source_size, struct cbor_load_result *result)

Loads data item from a buffer.

param source:

The buffer

param source_size:

param result:

[out] Result indicator. CBOR_ERR_NONE on success

return:

Decoded CBOR item. The item’s reference count is initialized to one.

return:

NULL on failure. In that case, result contains the location and description of the error.

Associated data structures

enum cbor_error_code

Possible decoding errors.

Values:

enumerator CBOR_ERR_NONE

enumerator CBOR_ERR_NOTENOUGHDATA

enumerator CBOR_ERR_NODATA

enumerator CBOR_ERR_MALFORMATED

enumerator CBOR_ERR_MEMERROR

Memory error - item allocation failed.

Is it too big for your allocator?

enumerator CBOR_ERR_SYNTAXERROR

Stack parsing algorithm failed.

struct cbor_load_result

High-level decoding result.

Public Members

struct cbor_error error

Error indicator.

size_t read

Number of bytes read.

struct cbor_error

High-level decoding error.

Public Members

size_t position

Approximate position.

cbor_error_code code

Description.