libcbor

Documentation for version 0.11.0, updated on May 14, 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)

Contents

• Getting started
  • Building & installing libcbor
  • Linking with libcbor
  • Troubleshooting
• Usage & preliminaries
  • Version information
  • Headers to include
  • Using libcbor
• API
  • Types of items
    • cbor_type
      • cbor_type::CBOR_TYPE_UINT
      • cbor_type::CBOR_TYPE_NEGINT
      • cbor_type::CBOR_TYPE_BYTESTRING
      • cbor_type::CBOR_TYPE_STRING
      • cbor_type::CBOR_TYPE_ARRAY
      • cbor_type::CBOR_TYPE_MAP
      • cbor_type::CBOR_TYPE_TAG
      • cbor_type::CBOR_TYPE_FLOAT_CTRL
    • cbor_typeof()
    • Binary queries
      • cbor_isa_uint()
      • cbor_isa_negint()
      • cbor_isa_bytestring()
      • cbor_isa_string()
      • cbor_isa_array()
      • cbor_isa_map()
      • cbor_isa_tag()
      • cbor_isa_float_ctrl()
    • Logical queries
      • cbor_is_int()
      • cbor_is_float()
      • cbor_is_bool()
      • cbor_is_null()
      • cbor_is_undef()
  • Memory management and reference counting
    • Using custom allocator
      • cbor_set_allocs()
    • Reference counting
      • cbor_incref()
      • cbor_decref()
      • cbor_intermediate_decref()
      • cbor_refcount()
      • cbor_move()
      • cbor_copy()
  • Decoding
    • cbor_load()
    • Associated data structures
      • cbor_error_code
        • cbor_error_code::CBOR_ERR_NONE
        • cbor_error_code::CBOR_ERR_NOTENOUGHDATA
        • cbor_error_code::CBOR_ERR_NODATA
        • cbor_error_code::CBOR_ERR_MALFORMATED
        • cbor_error_code::CBOR_ERR_MEMERROR
        • cbor_error_code::CBOR_ERR_SYNTAXERROR
      • cbor_load_result
      • error
      • read
      • cbor_error
      • position
      • code
  • Encoding
    • cbor_serialize()
    • cbor_serialize_alloc()
    • cbor_serialized_size()
    • Type-specific serializers
      • cbor_serialize_uint()
      • cbor_serialize_negint()
      • cbor_serialize_bytestring()
      • cbor_serialize_string()
      • cbor_serialize_array()
      • cbor_serialize_map()
      • cbor_serialize_tag()
      • cbor_serialize_float_ctrl()
  • Streaming Decoding
    • cbor_stream_decode()
    • cbor_callbacks
    • uint8
    • uint16
    • uint32
    • uint64
    • negint64
    • negint32
    • negint16
    • negint8
    • byte_string_start
    • byte_string
    • string
    • string_start
    • indef_array_start
    • array_start
    • indef_map_start
    • map_start
    • tag
    • float2
    • float4
    • float8
    • undefined
    • null
    • boolean
    • indef_break
    • cbor_empty_callbacks
    • Callback types definition
      • cbor_int8_callback
      • cbor_int16_callback
      • cbor_int32_callback
      • cbor_int64_callback
      • cbor_simple_callback
      • cbor_string_callback
      • cbor_collection_callback
      • cbor_float_callback
      • cbor_double_callback
      • cbor_bool_callback
  • Streaming Encoding
    • cbor_encode_uint8()
    • cbor_encode_uint16()
    • cbor_encode_uint32()
    • cbor_encode_uint64()
    • cbor_encode_uint()
    • cbor_encode_negint8()
    • cbor_encode_negint16()
    • cbor_encode_negint32()
    • cbor_encode_negint64()
    • cbor_encode_negint()
    • cbor_encode_bytestring_start()
    • cbor_encode_indef_bytestring_start()
    • cbor_encode_string_start()
    • cbor_encode_indef_string_start()
    • cbor_encode_array_start()
    • cbor_encode_indef_array_start()
    • cbor_encode_map_start()
    • cbor_encode_indef_map_start()
    • cbor_encode_tag()
    • cbor_encode_bool()
    • cbor_encode_null()
    • cbor_encode_undef()
    • cbor_encode_half()
    • cbor_encode_single()
    • cbor_encode_double()
    • cbor_encode_break()
    • cbor_encode_ctrl()
  • Types 0 & 1 – Positive and negative integers
    • cbor_int_width
      • cbor_int_width::CBOR_INT_8
      • cbor_int_width::CBOR_INT_16
      • cbor_int_width::CBOR_INT_32
      • cbor_int_width::CBOR_INT_64
    • Type 0 - positive integers
    • Type 1 - negative integers
    • Type 0 & 1
    • Building new items
      • cbor_build_uint8()
      • cbor_build_uint16()
      • cbor_build_uint32()
      • cbor_build_uint64()
    • Retrieving values
      • cbor_get_uint8()
      • cbor_get_uint16()
      • cbor_get_uint32()
      • cbor_get_uint64()
    • Setting values
      • cbor_set_uint8()
      • cbor_set_uint16()
      • cbor_set_uint32()
      • cbor_set_uint64()
    • Dealing with width
      • cbor_int_get_width()
    • Dealing with signedness
      • cbor_mark_uint()
      • cbor_mark_negint()
    • Creating new items
      • cbor_new_int8()
      • cbor_new_int16()
      • cbor_new_int32()
      • cbor_new_int64()
  • Type 2 – Byte strings
    • Getting metadata
      • cbor_bytestring_length()
      • cbor_bytestring_is_definite()
      • cbor_bytestring_is_indefinite()
      • cbor_bytestring_chunk_count()
    • Reading data
      • cbor_bytestring_handle()
      • cbor_bytestring_chunks_handle()
    • Creating new items
      • cbor_new_definite_bytestring()
      • cbor_new_indefinite_bytestring()
    • Building items
      • cbor_build_bytestring()
    • Manipulating existing items
      • cbor_bytestring_set_handle()
      • cbor_bytestring_add_chunk()
  • Type 3 – UTF-8 strings
    • UTF-8 encoding validation
    • Getting metadata
      • cbor_string_length()
      • cbor_string_is_definite()
      • cbor_string_is_indefinite()
      • cbor_string_chunk_count()
    • Reading data
      • cbor_string_handle()
      • cbor_string_chunks_handle()
    • Creating new items
      • cbor_new_definite_string()
      • cbor_new_indefinite_string()
    • Building items
      • cbor_build_string()
    • Manipulating existing items
      • cbor_string_set_handle()
      • cbor_string_add_chunk()
  • Type 4 – Arrays
    • Examples
    • Getting metadata
      • cbor_array_size()
      • cbor_array_allocated()
      • cbor_array_is_definite()
      • cbor_array_is_indefinite()
    • Reading data
      • cbor_array_handle()
      • cbor_array_get()
    • Creating new items
      • cbor_new_definite_array()
      • cbor_new_indefinite_array()
    • Modifying items
      • cbor_array_push()
      • cbor_array_replace()
      • cbor_array_set()
  • Type 5 – Maps
    • Examples
    • Getting metadata
      • cbor_map_size()
      • cbor_map_allocated()
      • cbor_map_is_definite()
      • cbor_map_is_indefinite()
    • Reading data
      • cbor_map_handle()
    • Creating new items
      • cbor_new_definite_map()
      • cbor_new_indefinite_map()
    • Modifying items
      • cbor_map_add()
  • Type 6 – Semantic tags
    • cbor_new_tag()
    • cbor_tag_item()
    • cbor_tag_value()
    • cbor_tag_set_item()
  • Type 7 – Floats & control tokens
    • cbor_float_width
      • cbor_float_width::CBOR_FLOAT_0
      • cbor_float_width::CBOR_FLOAT_16
      • cbor_float_width::CBOR_FLOAT_32
      • cbor_float_width::CBOR_FLOAT_64
    • Getting metadata
      • cbor_float_ctrl_is_ctrl()
      • cbor_float_get_width()
    • Reading data
      • cbor_float_get_float2()
      • cbor_float_get_float4()
      • cbor_float_get_float8()
      • cbor_float_get_float()
      • cbor_ctrl_value()
      • cbor_get_bool()
    • Creating new items
      • cbor_new_ctrl()
      • cbor_new_float2()
      • cbor_new_float4()
      • cbor_new_float8()
      • cbor_new_null()
      • cbor_new_undef()
    • Building items
      • cbor_build_bool()
      • cbor_build_ctrl()
      • cbor_build_float2()
      • cbor_build_float4()
      • cbor_build_float8()
    • Manipulating existing items
      • cbor_set_ctrl()
      • cbor_set_bool()
      • cbor_set_float2()
      • cbor_set_float4()
      • cbor_set_float8()
    • Half floats
• Tests
  • Unit tests
  • Testing for memory leaks
  • Code coverage
  • Fuzz testing
• IETF standard conformance
  • Bytestring length
  • “Half-precision” IEEE 754 floats
• Internal mechanics
  • Terminology
  • Conventions
  • Inspiration & related projects
  • General notes on the API design
  • Coding style
  • Memory layout
    • cbor_item_t
      • cbor_item_t::type
      • cbor_item_t::refcount
      • cbor_item_t::metadata
      • cbor_item_t::data
    • cbor_item_metadata
      • cbor_item_metadata::int_metadata
      • cbor_item_metadata::bytestring_metadata
      • cbor_item_metadata::string_metadata
      • cbor_item_metadata::array_metadata
      • cbor_item_metadata::map_metadata
      • cbor_item_metadata::tag_metadata
      • cbor_item_metadata::float_ctrl_metadata
  • Decoding
• Changelog
  • Next
  • 0.11.0 (2024-02-04)
  • 0.10.2 (2023-01-31)
  • 0.10.1 (2022-12-30)
  • 0.10.0 (2022-12-29)
  • 0.9.0 (2021-11-14)
  • 0.8.0 (2020-09-20)
  • 0.7.0 (2020-04-25)
  • 0.6.1 (2020-03-26)
  • 0.6.0 (2020-03-15)
  • 0.5.0 (2017-02-06)
  • 0.4.0 (2015-12-25)
  • 0.3.1 (2015-05-21)
  • 0.3.0 (2015-05-21)
  • 0.2.1 (2015-05-17)
  • 0.2.0 (2015-05-17)
  • 0.1.0 (2015-05-06)
• Development
  • Vision and principles
    • Mission statement
    • Goals
      • Standard conformance and full feature support
      • Safety
      • Self-containment
      • Portability
      • Stable and predictable API
      • Performance
    • Non-goals
  • Development dependencies
    • Installing sphinx
    • Live preview of docs
    • Set up git hooks
    • Testing and code coverage