1LIBCBOR(3) libcbor LIBCBOR(3)
2
6 libcbor - libcbor Documentation
7 Documentation for version 0.10.2, updated on Jul 20, 2023.
9
11 libcbor is a C library for parsing and generating CBOR, the gen‐
12 eral-purpose schema-less binary data format.
13 Main features
15 • Complete RFC conformance [1]
17 • Robust C99 implementation
19 • Layered architecture offers both control and convenience
21 • Flexible memory management
23 • No shared global state - threading friendly [2]
25 • Proper handling of UTF-8
27 • Full support for streams & incremental processing
29 • Extensive documentation and test suite
31 • No runtime dependencies, small footprint
33 [1] See RFC conformance
35 [2] With the exception of custom memory allocators (see Memory manage‐
37 ment and reference counting)
38
40 Getting started
41 Pre-built Linux packages are available in most mainstream distributions
42 Ubuntu, Debian, etc.:
44 apt-get install libcbor-dev
46 Fedora, openSUSE, etc.:
48 yum install libcbor-devel
50 OS X users can use Homebrew:
52 brew install libcbor
54 For other platforms, you will need to compile it from source.
56 Building & installing libcbor
58 Prerequisites:
59 • C99 compiler
61 • CMake 2.8 or newer (might also be called cmakesetup, cmake-gui
63 or ccmake depending on the installed version and system)
64 • C build system CMake can target (make, Apple Xcode, MinGW,
66 ...)
67 Configuration options
69 A handful of configuration flags can be passed to cmake. The following
71 table lists libcbor compile-time directives and several important
72 generic flags.
73 ┌──────────────────┬──────────────────┬──────────────────┬──────────────────┐
75 │Option │ Meaning │ Default │ Possible values │
76 ├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
77 │CMAKE_C_COMPILER │ C compiler to │ cc │ gcc, clang, │
78 │ │ use │ │ clang-3.5, ... │
79 ├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
80 │CMAKE_IN‐ │ Installation │ System-dependent │ /usr/local/lib, │
81 │STALL_PREFIX │ prefix │ │ ... │
82 ├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
83 │BUILD_SHARED_LIBS │ Build as a │ OFF │ ON, OFF │
84 │ │ shared library │ │ │
85 ├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
86 │HUGE_FUZZ │ Fuzz test with │ OFF │ ON, OFF │
87 │ │ 8GB of data │ │ │
88 ├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
89 │SANE_MALLOC │ Assume malloc │ OFF │ ON, OFF │
90 │ │ will refuse un‐ │ │ │
91 │ │ reasonable allo‐ │ │ │
92 │ │ cations │ │ │
93 ├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
94 │COVERAGE │ Generate test │ OFF │ ON, OFF │
95 │ │ coverage instru‐ │ │ │
96 │ │ mentation │ │ │
97 ├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
98 │WITH_TESTS │ Build unit tests │ OFF │ ON, OFF │
99 │ │ (see │ │ │
100 │ │ Development) │ │ │
101 └──────────────────┴──────────────────┴──────────────────┴──────────────────┘
102 The following configuration options will also be defined as macros [1]
104 in <cbor/common.h> and can therefore be used in client code:
105 ┌────────────────────┬──────────────────┬─────────┬─────────────────┐
107 │Option │ Meaning │ Default │ Possible values │
108 ├────────────────────┼──────────────────┼─────────┼─────────────────┤
109 │CBOR_PRETTY_PRINTER │ Include a │ ON │ ON, OFF │
110 │ │ pretty-printing │ │ │
111 │ │ routine │ │ │
112 ├────────────────────┼──────────────────┼─────────┼─────────────────┤
113 │CBOR_BUFFER_GROWTH │ Factor for buf‐ │ 2 │ Decimals > 1 │
114 │ │ fer growth & │ │ │
115 │ │ shrinking │ │ │
116 └────────────────────┴──────────────────┴─────────┴─────────────────┘
117 [1] ON & OFF will be translated to 1 and 0 using cmakedefine.
119 If you want to pass other custom configuration options, please re‐
121 fer to http://www.cmake.org/Wiki/CMake_Useful_Variables.
122 WARNING:
124 CBOR_CUSTOM_ALLOC has been removed. Custom allocators (historically
125 a controlled by a build flag) are always enabled.
126 Building using make
128 CMake will generate a Makefile and other configuration files for the
130 build. As a rule of thumb, you should configure the build outside of
131 the source tree in order to keep different configurations isolated. If
132 you are unsure where to execute the build, just use a temporary direc‐
133 tory:
134 cd $(mktemp -d /tmp/cbor_build.XXXX)
136 Now, assuming you are in the directory where you want to build, build
138 libcbor as a static library:
139 cmake -DCMAKE_BUILD_TYPE=Release path_to_libcbor_dir
141 make cbor
142 ... or as a dynamic library:
144 cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON path_to_libcbor_dir
146 make cbor
147 To install locally:
149 make install
151 Root permissions are required on most systems when using the default
153 installation prefix.
154 Portability
156 libcbor is highly portable and works on both little- and big-endian
158 systems regardless of the operating system. After building on an exotic
159 platform, you might wish to verify the result by running the test
160 suite. If you encounter any problems, please report them to the issue
161 tracker.
162 libcbor is known to successfully work on ARM Android devices.
164 Cross-compilation is possible with arm-linux-gnueabi-gcc.
165 Linking with libcbor
167 If you include and linker paths include the directories to which libc‐
168 bor has been installed, compiling programs that uses libcbor requires
169 no extra considerations.
170 You can verify that everything has been set up properly by creating a
172 file with the following contents
173 #include <cbor.h>
175 #include <stdio.h>
176 int main(int argc, char * argv[])
178 {
179 printf("Hello from libcbor %s\n", CBOR_VERSION);
180 }
181 and compiling it
183 cc hello_cbor.c -lcbor -o hello_cbor
185 libcbor also comes with pkg-config support. If you install libcbor with
187 a custom prefix, you can use pkg-config to resolve the headers and ob‐
188 jects:
189 cc $(pkg-config --cflags libcbor) hello_cbor.c $(pkg-config --libs libcbor) -o hello_cbor
191 A note on linkage
193 libcbor is primarily intended to be linked statically. The shared li‐
195 brary versioning scheme generally follows SemVer, but is irregular for
196 the 0.X.Y development branch for historical reasons. The following ver‐
197 sion identifiers are used as a part of the SONAME (Linux) or the dylib
198 "Compatibility version" (OS X):
199 • 0.Y for the 0.Y.Z branch. Patches are backwards compatible, minor
201 releases are generally not and require re-compilation of any de‐
202 pendent code.
203 • X for the X.Y.Z stable versions starting 1.X.Y. All minor release
205 of the major version are backwards compatible.
206 WARNING:
208 Please note that releases up to and including v0.6.0 may export mis‐
209 leading .so/.dylib version number.
210 Troubleshooting
212 cbor.h not found: The headers directory is probably not in your include
213 path. First, verify the installation location by checking the installa‐
214 tion log. If you used make, it will look something like
215 ...
217 -- Installing: /usr/local/include/cbor
218 -- Installing: /usr/local/include/cbor/callbacks.h
219 -- Installing: /usr/local/include/cbor/encoding.h
220 ...
221 Make sure that CMAKE_INSTALL_PREFIX (if you provided it) was correct.
223 Including the path path during compilation should suffice, e.g.:
224 cc -I/usr/local/include hello_cbor.c -lcbor -o hello_cbor
226 cannot find -lcbor during linking: Most likely the same problem as be‐
228 fore. Include the installation directory in the linker shared path us‐
229 ing -R, e.g.:
230 cc -Wl,-rpath,/usr/local/lib -lcbor -o hello_cbor
232 shared library missing during execution: Verify the linkage using ldd,
234 otool, or similar and adjust the compilation directives accordingly:
235 ⇒ ldd hello_cbor
237 linux-vdso.so.1 => (0x00007ffe85585000)
238 libcbor.so => /usr/local/lib/libcbor.so (0x00007f9af69da000)
239 libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f9af65eb000)
240 /lib64/ld-linux-x86-64.so.2 (0x00007f9af6be9000)
241 compilation failed: If your compiler supports C99 yet the compilation
243 has failed, please report the issue to the issue tracker.
244 Usage & preliminaries
246 Version information
247 libcbor exports its version using three self-explanatory macros:
248 • CBOR_MAJOR_VERSION
250 • CBOR_MINOR_VERSION
252 • CBOR_PATCH_VERSION
254 The CBOR_VERSION is a string concatenating these three identifiers into
256 one (e.g. 0.2.0).
257 In order to simplify version comparisons, the version is also exported
259 as
260 #define CBOR_HEX_VERSION ((CBOR_MAJOR_VERSION << 16) | (CBOR_MINOR_VERSION << 8) | CBOR_PATCH_VERSION)
262 Since macros are difficult to work with through FFIs, the same informa‐
264 tion is also available through three uint8_t constants, namely
265 • cbor_major_version
267 • cbor_minor_version
269 • cbor_patch_version
271 Headers to include
273 The cbor.h header includes all the symbols. If, for any reason, you
274 don't want to include all the exported symbols, feel free to use just
275 some of the cbor/*.h headers:
276 • cbor/arrays.h - Type 4 – Arrays
278 • cbor/bytestrings.h - Type 2 – Byte strings
280 • cbor/callbacks.h - Callbacks used for Streaming Decoding
282 • cbor/common.h - Common utilities - always transitively included
284 • cbor/data.h - Data types definitions - always transitively in‐
286 cluded
287 • cbor/encoding.h - Streaming encoders for Streaming Encoding
289 • cbor/floats_ctrls.h - Type 7 – Floats & control tokens
291 • cbor/ints.h - Types 0 & 1 – Positive and negative integers
293 • cbor/maps.h - Type 5 – Maps
295 • cbor/serialization.h - High level serialization such as
297 cbor_serialize()
298 • cbor/streaming.h - Home of cbor_stream_decode()
300 • cbor/strings.h - Type 3 – UTF-8 strings
302 • cbor/tags.h - Type 6 – Semantic tags
304 Using libcbor
306 If you want to get more familiar with CBOR, we recommend the cbor.io
307 website. Once you get the grasp of what is it CBOR does, the examples
308 (located in the examples directory) should give you a good feel of the
309 API. The API documentation should then provide with all the information
310 you may need.
311 Creating and serializing items
313 #include "cbor.h"
315 #include <stdio.h>
316 int main(int argc, char * argv[])
318 {
319 /* Preallocate the map structure */
320 cbor_item_t * root = cbor_new_definite_map(2);
321 /* Add the content */
322 cbor_map_add(root, (struct cbor_pair) {
323 .key = cbor_move(cbor_build_string("Is CBOR awesome?")),
324 .value = cbor_move(cbor_build_bool(true))
325 });
326 cbor_map_add(root, (struct cbor_pair) {
327 .key = cbor_move(cbor_build_uint8(42)),
328 .value = cbor_move(cbor_build_string("Is the answer"))
329 });
330 /* Output: `buffer_size` bytes of data in the `buffer` */
331 unsigned char * buffer;
332 size_t buffer_size;
333 cbor_serialize_alloc(root, &buffer, &buffer_size);
334 fwrite(buffer, 1, buffer_size, stdout);
336 free(buffer);
337 fflush(stdout);
339 cbor_decref(&root);
340 }
341 Reading serialized data
343 #include "cbor.h"
345 #include <stdio.h>
346 /*
348 * Reads data from a file. Example usage:
349 * $ ./examples/readfile examples/data/nested_array.cbor
350 */
351 int main(int argc, char * argv[])
353 {
354 FILE * f = fopen(argv[1], "rb");
355 fseek(f, 0, SEEK_END);
356 size_t length = (size_t)ftell(f);
357 fseek(f, 0, SEEK_SET);
358 unsigned char * buffer = malloc(length);
359 fread(buffer, length, 1, f);
360 /* Assuming `buffer` contains `info.st_size` bytes of input data */
362 struct cbor_load_result result;
363 cbor_item_t * item = cbor_load(buffer, length, &result);
364 /* Pretty-print the result */
365 cbor_describe(item, stdout);
366 fflush(stdout);
367 /* Deallocate the result */
368 cbor_decref(&item);
369 fclose(f);
371 }
372 Using the streaming parser
374 #include "cbor.h"
376 #include <stdio.h>
377 #include <string.h>
378 /*
380 * Illustrates how one might skim through a map (which is assumed to have
381 * string keys and values only), looking for the value of a specific key
382 *
383 * Use the examples/data/map.cbor input to test this.
384 */
385 const char * key = "a secret key";
387 bool key_found = false;
388 void find_string(void * _ctx, cbor_data buffer, size_t len)
390 {
391 if (key_found) {
392 printf("Found the value: %*s\n", (int) len, buffer);
393 key_found = false;
394 } else if (len == strlen(key)) {
395 key_found = (memcmp(key, buffer, len) == 0);
396 }
397 }
398 int main(int argc, char * argv[])
400 {
401 FILE * f = fopen(argv[1], "rb");
402 fseek(f, 0, SEEK_END);
403 size_t length = (size_t)ftell(f);
404 fseek(f, 0, SEEK_SET);
405 unsigned char * buffer = malloc(length);
406 fread(buffer, length, 1, f);
407 struct cbor_callbacks callbacks = cbor_empty_callbacks;
409 struct cbor_decoder_result decode_result;
410 size_t bytes_read = 0;
411 callbacks.string = find_string;
412 while (bytes_read < length) {
413 decode_result = cbor_stream_decode(buffer + bytes_read,
414 length - bytes_read,
415 &callbacks, NULL);
416 bytes_read += decode_result.read;
417 }
418 fclose(f);
420 }
421 API
423 The data API is centered around cbor_item_t, a generic handle for any
424 CBOR item. There are functions to
425 • create items,
427 • set items' data,
429 • parse serialized data into items,
431 • manage, move, and links item together.
433 The single most important thing to keep in mind is: cbor_item_t is an
435 opaque type and should only be manipulated using the appropriate func‐
436 tions! Think of it as an object.
437 The libcbor API closely follows the semantics outlined by CBOR stan‐
439 dard. This part of the documentation provides a short overview of the
440 CBOR constructs, as well as a general introduction to the libcbor API.
441 Remaining reference can be found in the following files structured by
442 data types.
443 The API is designed to allow both very tight control & flexibility and
445 general convenience with sane defaults. [1] For example, client with
446 very specific requirements (constrained environment, custom application
447 protocol built on top of CBOR, etc.) may choose to take full control
448 (and responsibility) of memory and data structures management by inter‐
449 acting directly with the decoder. Other clients might want to take con‐
450 trol of specific aspects (streamed collections, hash maps storage), but
451 leave other responsibilities to libcbor. More general clients might
452 prefer to be abstracted away from all aforementioned details and only
453 be presented complete data structures.
454 libcbor provides
456 • stateless encoders and decoders
458 • encoding and decoding drivers, routines that coordinate encod‐
460 ing and decoding of complex structures
461 • data structures to represent and transform CBOR structures
463 • routines for building and manipulating these structures
465 • utilities for inspection and debugging
467 Types of items
469 Every cbor_item_t has a cbor_type associated with it - these constants
470 correspond to the types specified by the CBOR standard:
471 enum cbor_type
473 Specifies the Major type of cbor_item_t.
474 Values:
476 enumerator CBOR_TYPE_UINT
478 0 - positive integers
479 enumerator CBOR_TYPE_NEGINT
481 1 - negative integers
482 enumerator CBOR_TYPE_BYTESTRING
484 2 - byte strings
485 enumerator CBOR_TYPE_STRING
487 3 - strings
488 enumerator CBOR_TYPE_ARRAY
490 4 - arrays
491 enumerator CBOR_TYPE_MAP
493 5 - maps
494 enumerator CBOR_TYPE_TAG
496 6 - tags
497 enumerator CBOR_TYPE_FLOAT_CTRL
499 7 - decimals and special values (true, false, nil, ...)
500 To find out the type of an item, one can use
502 cbor_type cbor_typeof(const cbor_item_t *item)
504 Get the type of the item.
505 param item
507 return The type
510 Please note the distinction between functions like cbor_isa_uint() and
512 cbor_is_int(). The following functions work solely with the major type
513 value.
514 Binary queries
516 Alternatively, there are functions to query each particular type.
517 WARNING:
519 Passing an invalid cbor_item_t reference to any of these functions
520 results in undefined behavior.
521 bool cbor_isa_uint(const cbor_item_t *item)
523 Does the item have the appropriate major type?
524 param item
526 the item
527 return Is the item an CBOR_TYPE_UINT?
529 bool cbor_isa_negint(const cbor_item_t *item)
531 Does the item have the appropriate major type?
532 param item
534 the item
535 return Is the item a CBOR_TYPE_NEGINT?
537 bool cbor_isa_bytestring(const cbor_item_t *item)
539 Does the item have the appropriate major type?
540 param item
542 the item
543 return Is the item a CBOR_TYPE_BYTESTRING?
545 bool cbor_isa_string(const cbor_item_t *item)
547 Does the item have the appropriate major type?
548 param item
550 the item
551 return Is the item a CBOR_TYPE_STRING?
553 bool cbor_isa_array(const cbor_item_t *item)
555 Does the item have the appropriate major type?
556 param item
558 the item
559 return Is the item an CBOR_TYPE_ARRAY?
561 bool cbor_isa_map(const cbor_item_t *item)
563 Does the item have the appropriate major type?
564 param item
566 the item
567 return Is the item a CBOR_TYPE_MAP?
569 bool cbor_isa_tag(const cbor_item_t *item)
571 Does the item have the appropriate major type?
572 param item
574 the item
575 return Is the item a CBOR_TYPE_TAG?
577 bool cbor_isa_float_ctrl(const cbor_item_t *item)
579 Does the item have the appropriate major type?
580 param item
582 the item
583 return Is the item a CBOR_TYPE_FLOAT_CTRL?
585 Logical queries
587 These functions provide information about the item type from a more
588 high-level perspective
589 bool cbor_is_int(const cbor_item_t *item)
591 Is the item an integer, either positive or negative?
592 param item
594 the item
595 return Is the item an integer, either positive or negative?
597 bool cbor_is_float(const cbor_item_t *item)
599 Is the item an a floating point number?
600 param item
602 the item
603 return Is the item a floating point number?
605 bool cbor_is_bool(const cbor_item_t *item)
607 Is the item an a boolean?
608 param item
610 the item
611 return Is the item a boolean?
613 bool cbor_is_null(const cbor_item_t *item)
615 Does this item represent null
616 WARNING:
618 This is in no way related to the value of the pointer. Pass‐
619 ing a null pointer will most likely result in a crash.
620 param item
622 the item
623 return Is the item (CBOR logical) null?
625 bool cbor_is_undef(const cbor_item_t *item)
627 Does this item represent undefined
628 WARNING:
630 Care must be taken to distinguish nulls and undefined values
631 in C.
632 param item
634 the item
635 return Is the item (CBOR logical) undefined?
637 Memory management and reference counting
639 Due to the nature of its domain, libcbor will need to work with heap
640 memory. The stateless decoder and encoder doesn't allocate any memory.
641 If you have specific requirements, you should consider rolling your own
643 driver for the stateless API.
644 Using custom allocator
646 libcbor gives you with the ability to provide your own implementations
647 of malloc, realloc, and free. This can be useful if you are using a
648 custom allocator throughout your application, or if you want to imple‐
649 ment custom policies (e.g. tighter restrictions on the amount of allo‐
650 cated memory).
651 cbor_set_allocs(malloc, realloc, free);
653 void cbor_set_allocs(_cbor_malloc_t custom_malloc, _cbor_realloc_t cus‐
655 tom_realloc, _cbor_free_t custom_free)
656 Sets the memory management routines to use.
657 By default, libcbor will use the standard library malloc, real‐
659 loc, and free.
660 NOTE:
662 realloc implementation must correctly support NULL realloca‐
663 tion (see e.g. http://en.cppreference.com/w/c/memory/realloc)
664 WARNING:
666 This function modifies the global state and should therefore
667 be used accordingly. Changing the memory handlers while allo‐
668 cated items exist will result in a free/malloc mismatch. This
669 function is not thread safe with respect to both itself and
670 all the other libcbor functions that work with the heap.
671 param custom_malloc
673 malloc implementation
674 param custom_realloc
676 realloc implementation
677 param custom_free
679 free implementation
680 Reference counting
682 As CBOR items may require complex cleanups at the end of their life‐
683 time, there is a reference counting mechanism in place. This also en‐
684 ables a very simple GC when integrating libcbor into a managed environ‐
685 ment. Every item starts its life (by either explicit creation, or as a
686 result of parsing) with reference count set to 1. When the refcount
687 reaches zero, it will be destroyed.
688 Items containing nested items will be destroyed recursively - the ref‐
690 count of every nested item will be decreased by one.
691 The destruction is synchronous and renders any pointers to items with
693 refcount zero invalid immediately after calling cbor_decref().
694 cbor_item_t *cbor_incref(cbor_item_t *item)
696 Increases the item's reference count by one.
697 Constant complexity; items referring to this one or items being
699 referred to are not updated.
700 This function can be used to extend reference counting to client
702 code.
703 param item
705 Reference to an item
706 return The input item
708 void cbor_decref(cbor_item_t **item)
710 Decreases the item's reference count by one, deallocating the
711 item if needed.
712 In case the item is deallocated, the reference count of all
714 items this item references will also be cbor_decref 'ed recur‐
715 sively.
716 param item
718 Reference to an item. Will be set to NULL if deallocated
719 void cbor_intermediate_decref(cbor_item_t *item)
721 Decreases the item's reference count by one, deallocating the
722 item if needed.
723 Convenience wrapper for cbor_decref when its set-to-null behav‐
725 ior is not needed
726 param item
728 Reference to an item
729 size_t cbor_refcount(const cbor_item_t *item)
731 Get the item's reference count.
732 Todo: Add some inline examples for reference counting
735 WARNING:
738 This does not account for transitive references.
739 param item
741 the item
742 return the reference count
744 cbor_item_t *cbor_move(cbor_item_t *item)
746 Provides CPP-like move construct.
747 Decreases the reference count by one, but does not deallocate
749 the item even if its refcount reaches zero. This is useful for
750 passing intermediate values to functions that increase reference
751 count. Should only be used with functions that incref their ar‐
752 guments.
753 WARNING:
755 If the item is moved without correctly increasing the refer‐
756 ence count afterwards, the memory will be leaked.
757 param item
759 Reference to an item
760 return the item with reference count decreased by one
762 cbor_item_t *cbor_copy(cbor_item_t *item)
764 Take a deep copy of an item.
765 All items this item points to (array and map members, string
767 chunks, tagged items) will be copied recursively using
768 cbor_copy. The new item doesn't alias or point to any items from
769 the original item. All the reference counts in the new structure
770 are set to one.
771 param item
773 item to copy
774 return Reference to the new item. The item's reference count is
776 initialized to one.
777 return NULL if memory allocation fails
779 Decoding
781 The following diagram illustrates the relationship among different
782 parts of libcbor from the decoding standpoint.
783 ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
785 │ │
786 │ Client application │
787 │ │
788 │ ┌────────────────────────────────────────────┘
789 │ │ ↕
790 │ │ ┌──────────────────────────────────────────┐
791 │ │ │ │
792 │ │ │ Manipulation routines │
793 │ │ │ │
794 │ ┌─────────────────────────────────────┘ └──────────────────────────────────────────┘
795 │ │ ↑ ↑ ↑ ↑
796 │ │ │ │ ┌─────────────╫──────────┬───────────────────┴─┐
797 │ │ │ CDS │ ║ │ │
798 │ │ │ │ PDS ║ PDS PDS
799 │ │ ↓ ↓ ↓ ↓ ↓ ↓
800 │ │ ┌─────────────────┐ ┌────────────────────┐ ┌────────────────────────────┐
801 │ │ │ │ │ │ │ │
802 │ │ │ Custom driver │ ↔ │ Streaming driver │ ↔ │ Default driver │ ↔ CD
803 │ │ │ │ │ │ │ │
804 └───────────┘ └─────────────────┘ └────────────────────┘ └────────────────────────────┘
805 ↕ ↕ ↕ ↕
806 ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
807 │ │
808 │ Stateless event─driven decoder │
809 │ │
810 └──────────────────────────────────────────────────────────────────────────────────────────────┘
811 (PSD = Provided Data Structures, CDS = Custom Data Structures)
813 This section will deal with the API that is labeled as the "Default
815 driver" in the diagram. That is, routines that decode complete libcbor
816 data items
817 cbor_item_t *cbor_load(cbor_data source, size_t source_size, struct
819 cbor_load_result *result)
820 Loads data item from a buffer.
821 param source
823 The buffer
824 param source_size
826 param result
829 [out] Result indicator. CBOR_ERR_NONE on success
830 return Decoded CBOR item. The item's reference count is initial‐
832 ized to one.
833 return NULL on failure. In that case, result contains the loca‐
835 tion and description of the error.
836 Associated data structures
838 enum cbor_error_code
839 Possible decoding errors.
840 Values:
842 enumerator CBOR_ERR_NONE
844 enumerator CBOR_ERR_NOTENOUGHDATA
846 enumerator CBOR_ERR_NODATA
848 enumerator CBOR_ERR_MALFORMATED
850 enumerator CBOR_ERR_MEMERROR
852 Memory error - item allocation failed.
853 Is it too big for your allocator?
855 enumerator CBOR_ERR_SYNTAXERROR
857 Stack parsing algorithm failed.
858 struct cbor_load_result
860 High-level decoding result.
861 Public Members
863 struct cbor_error error
865 Error indicator.
866 size_t read
868 Number of bytes read.
869 struct cbor_error
871 High-level decoding error.
872 Public Members
874 size_t position
876 Approximate position.
877 cbor_error_code code
879 Description.
880 Encoding
882 The easiest way to encode data items is using the cbor_serialize() or
883 cbor_serialize_alloc() functions:
884 size_t cbor_serialize(const cbor_item_t *item, cbor_mutable_data buf‐
886 fer, size_t buffer_size)
887 Serialize the given item.
888 param item
890 A data item
891 param buffer
893 Buffer to serialize to
894 param buffer_size
896 Size of the buffer
897 return Length of the result. 0 on failure.
899 size_t cbor_serialize_alloc(const cbor_item_t *item, unsigned char
901 **buffer, size_t *buffer_size)
902 Serialize the given item, allocating buffers as needed.
903 Since libcbor v0.10, the return value is always the same as buf‐
905 fer_size (if provided, see
906 https://github.com/PJK/libcbor/pull/251/). New clients should
907 ignore the return value.
908 WARNING:
910 It is the caller's responsibility to free the buffer using an
911 appropriate free implementation.
912 param item
914 A data item
915 param buffer
917 [out] Buffer containing the result
918 param buffer_size
920 [out] Size of the buffer, or 0 on memory allocation fail‐
921 ure.
922 return Length of the result in bytes
924 return 0 on memory allocation failure, in which case buffer is
926 NULL.
927 To determine the number of bytes needed to serialize an item, use
929 cbor_serialized_size():
930 size_t cbor_serialized_size(const cbor_item_t *item)
932 Compute the length (in bytes) of the item when serialized using
933 cbor_serialize.
934 Time complexity is proportional to the number of nested items.
936 param item
938 A data item
939 return Length (>= 1) of the item when serialized. 0 if the
941 length overflows size_t.
942 Type-specific serializers
944 In case you know the type of the item you want to serialize beforehand,
945 you can use one of the type-specific serializers.
946 NOTE:
948 Unless compiled in debug mode, these do not verify the type. Passing
949 an incorrect item will result in an undefined behavior.
950 size_t cbor_serialize_uint(const cbor_item_t *item, cbor_mutable_data
952 buffer, size_t buffer_size)
953 Serialize an uint.
954 param item
956 A uint
957 param buffer
959 [out] Buffer to serialize to
960 param buffer_size
962 Size of the buffer
963 return Length of the result
965 return 0 if the buffer_size doesn't fit the result
967 size_t cbor_serialize_negint(const cbor_item_t *item, cbor_mutable_data
969 buffer, size_t buffer_size)
970 Serialize a negint.
971 param item
973 A negint
974 param buffer
976 [out] Buffer to serialize to
977 param buffer_size
979 Size of the buffer
980 return Length of the result
982 return 0 if the buffer_size doesn't fit the result
984 size_t cbor_serialize_bytestring(const cbor_item_t *item, cbor_muta‐
986 ble_data buffer, size_t buffer_size)
987 Serialize a bytestring.
988 param item
990 A bytestring
991 param buffer
993 [out] Buffer to serialize to
994 param buffer_size
996 Size of the buffer
997 return Length of the result
999 return 0 if the buffer_size doesn't fit the result. The buffer
1001 may still be modified
1002 size_t cbor_serialize_string(const cbor_item_t *item, cbor_mutable_data
1004 buffer, size_t buffer_size)
1005 Serialize a string.
1006 param item
1008 A string
1009 param buffer
1011 [out] Buffer to serialize to
1012 param buffer_size
1014 Size of the buffer
1015 return Length of the result
1017 return 0 if the buffer_size doesn't fit the result. The buffer
1019 may still be modified
1020 size_t cbor_serialize_array(const cbor_item_t *item, cbor_mutable_data
1022 buffer, size_t buffer_size)
1023 Serialize an array.
1024 param item
1026 An array
1027 param buffer
1029 [out] Buffer to serialize to
1030 param buffer_size
1032 Size of the buffer
1033 return Length of the result
1035 return 0 if the buffer_size doesn't fit the result. The buffer
1037 may still be modified
1038 size_t cbor_serialize_map(const cbor_item_t *item, cbor_mutable_data
1040 buffer, size_t buffer_size)
1041 Serialize a map.
1042 param item
1044 A map
1045 param buffer
1047 [out] Buffer to serialize to
1048 param buffer_size
1050 Size of the buffer
1051 return Length of the result
1053 return 0 if the buffer_size doesn't fit the result. The buffer
1055 may still be modified
1056 size_t cbor_serialize_tag(const cbor_item_t *item, cbor_mutable_data
1058 buffer, size_t buffer_size)
1059 Serialize a tag.
1060 param item
1062 A tag
1063 param buffer
1065 [out] Buffer to serialize to
1066 param buffer_size
1068 Size of the buffer
1069 return Length of the result
1071 return 0 if the buffer_size doesn't fit the result. The buffer
1073 may still be modified
1074 size_t cbor_serialize_float_ctrl(const cbor_item_t *item, cbor_muta‐
1076 ble_data buffer, size_t buffer_size)
1077 Serialize a.
1078 param item
1080 A float or ctrl
1081 param buffer
1083 [out] Buffer to serialize to
1084 param buffer_size
1086 Size of the buffer
1087 return Length of the result
1089 return 0 if the buffer_size doesn't fit the result
1091 Streaming Decoding
1093 libcbor exposes a stateless decoder that reads a stream of input bytes
1094 from a buffer and invokes user-provided callbacks as it decodes the in‐
1095 put:
1096 struct cbor_decoder_result cbor_stream_decode(cbor_data source, size_t
1098 source_size, const struct cbor_callbacks *callbacks, void *context)
1099 Stateless decoder.
1100 Will try parsing the source and will invoke the appropriate
1102 callback on success. Decodes one item at a time. No memory allo‐
1103 cations occur.
1104 param source
1106 Input buffer
1107 param source_size
1109 Length of the buffer
1110 param callbacks
1112 The callback bundle
1113 param context
1115 An arbitrary pointer to allow for maintaining context.
1116 For example, when cbor_stream_decode() encounters a 1B unsigned inte‐
1118 ger, it will invoke the function pointer stored in cbor_call‐
1119 backs.uint8. Complete usage example: examples/streaming_parser.c
1120 The callbacks are defined by
1122 struct cbor_callbacks
1124 Callback bundle — passed to the decoder.
1125 Public Members
1127 cbor_int8_callback uint8
1129 Unsigned int.
1130 cbor_int16_callback uint16
1132 Unsigned int.
1133 cbor_int32_callback uint32
1135 Unsigned int.
1136 cbor_int64_callback uint64
1138 Unsigned int.
1139 cbor_int64_callback negint64
1141 Negative int.
1142 cbor_int32_callback negint32
1144 Negative int.
1145 cbor_int16_callback negint16
1147 Negative int.
1148 cbor_int8_callback negint8
1150 Negative int.
1151 cbor_simple_callback byte_string_start
1153 Definite byte string.
1154 cbor_string_callback byte_string
1156 Indefinite byte string start.
1157 cbor_string_callback string
1159 Definite string.
1160 cbor_simple_callback string_start
1162 Indefinite string start.
1163 cbor_simple_callback indef_array_start
1165 Definite array.
1166 cbor_collection_callback array_start
1168 Indefinite array.
1169 cbor_simple_callback indef_map_start
1171 Definite map.
1172 cbor_collection_callback map_start
1174 Indefinite map.
1175 cbor_int64_callback tag
1177 Tags.
1178 cbor_float_callback float2
1180 Half float.
1181 cbor_float_callback float4
1183 Single float.
1184 cbor_double_callback float8
1186 Double float.
1187 cbor_simple_callback undefined
1189 Undef.
1190 cbor_simple_callback null
1192 Null.
1193 cbor_bool_callback boolean
1195 Bool.
1196 cbor_simple_callback indef_break
1198 Indefinite item break.
1199 When building custom sets of callbacks, feel free to start from
1201 const struct cbor_callbacks cbor_empty_callbacks
1203 Dummy callback bundle - does nothing.
1204 Callback types definition
1206 typedef void (*cbor_int8_callback)(void*, uint8_t)
1207 Callback prototype.
1208 typedef void (*cbor_int16_callback)(void*, uint16_t)
1210 Callback prototype.
1211 typedef void (*cbor_int32_callback)(void*, uint32_t)
1213 Callback prototype.
1214 typedef void (*cbor_int64_callback)(void*, uint64_t)
1216 Callback prototype.
1217 typedef void (*cbor_simple_callback)(void*)
1219 Callback prototype.
1220 typedef void (*cbor_string_callback)(void*, cbor_data, uint64_t)
1222 Callback prototype.
1223 typedef void (*cbor_collection_callback)(void*, uint64_t)
1225 Callback prototype.
1226 typedef void (*cbor_float_callback)(void*, float)
1228 Callback prototype.
1229 typedef void (*cbor_double_callback)(void*, double)
1231 Callback prototype.
1232 typedef void (*cbor_bool_callback)(void*, bool)
1234 Callback prototype.
1235 Streaming Encoding
1237 cbor/encoding.h exposes a low-level encoding API to encode CBOR objects
1238 on the fly. Unlike cbor_serialize(), these functions take logical val‐
1239 ues (integers, floats, strings, etc.) instead of cbor_item_t. The
1240 client is responsible for constructing the compound types correctly
1241 (e.g. terminating arrays).
1242 Streaming encoding is typically used to create an streaming (indefinite
1244 length) CBOR strings, byte strings, arrays, and maps. Complete example:
1245 examples/streaming_array.c
1246 size_t cbor_encode_uint8(uint8_t value, unsigned char *buffer, size_t
1248 buffer_size)
1249 size_t cbor_encode_uint16(uint16_t value, unsigned char *buffer, size_t
1251 buffer_size)
1252 size_t cbor_encode_uint32(uint32_t value, unsigned char *buffer, size_t
1254 buffer_size)
1255 size_t cbor_encode_uint64(uint64_t value, unsigned char *buffer, size_t
1257 buffer_size)
1258 size_t cbor_encode_uint(uint64_t value, unsigned char *buffer, size_t
1260 buffer_size)
1261 size_t cbor_encode_negint8(uint8_t value, unsigned char *buffer, size_t
1263 buffer_size)
1264 size_t cbor_encode_negint16(uint16_t value, unsigned char *buffer,
1266 size_t buffer_size)
1267 size_t cbor_encode_negint32(uint32_t value, unsigned char *buffer,
1269 size_t buffer_size)
1270 size_t cbor_encode_negint64(uint64_t value, unsigned char *buffer,
1272 size_t buffer_size)
1273 size_t cbor_encode_negint(uint64_t value, unsigned char *buffer, size_t
1275 buffer_size)
1276 size_t cbor_encode_bytestring_start(size_t length, unsigned char *buf‐
1278 fer, size_t buffer_size)
1279 size_t cbor_encode_indef_bytestring_start(unsigned char *buffer, size_t
1281 buffer_size)
1282 size_t cbor_encode_string_start(size_t length, unsigned char *buffer,
1284 size_t buffer_size)
1285 size_t cbor_encode_indef_string_start(unsigned char *buffer, size_t
1287 buffer_size)
1288 size_t cbor_encode_array_start(size_t length, unsigned char *buffer,
1290 size_t buffer_size)
1291 size_t cbor_encode_indef_array_start(unsigned char *buffer, size_t buf‐
1293 fer_size)
1294 size_t cbor_encode_map_start(size_t length, unsigned char *buffer,
1296 size_t buffer_size)
1297 size_t cbor_encode_indef_map_start(unsigned char *buffer, size_t buf‐
1299 fer_size)
1300 size_t cbor_encode_tag(uint64_t value, unsigned char *buffer, size_t
1302 buffer_size)
1303 size_t cbor_encode_bool(bool value, unsigned char *buffer, size_t buf‐
1305 fer_size)
1306 size_t cbor_encode_null(unsigned char *buffer, size_t buffer_size)
1308 size_t cbor_encode_undef(unsigned char *buffer, size_t buffer_size)
1310 size_t cbor_encode_half(float value, unsigned char *buffer, size_t buf‐
1312 fer_size)
1313 Encodes a half-precision float.
1314 Since there is no native representation or semantics for half
1316 floats in the language, we use single-precision floats, as every
1317 value that can be expressed as a half-float can also be ex‐
1318 pressed as a float.
1319 This however means that not all floats passed to this function
1321 can be unambiguously encoded. The behavior is as follows:.INDENT
1322 7.0
1323 • Infinity, NaN are preserved
1325 • Zero is preserved
1327 • Denormalized numbers keep their sign bit and 10 most significant bit
1329 of the significand
1330 • All other numbers.INDENT 2.0
1332 • If the logical value of the exponent is < -24, the output is zero
1334 • If the logical value of the exponent is between -23 and -14, the out‐
1336 put is cut off to represent the 'magnitude' of the input, by which we
1337 mean (-1)^{signbit} x 1.0e{exponent}. The value in the significand is
1338 lost.
1339 • In all other cases, the sign bit, the exponent, and 10 most signifi‐
1341 cant bits of the significand are kept
1342 size_t cbor_encode_single(float value, unsigned char *buffer, size_t
1346 buffer_size)
1347 size_t cbor_encode_double(double value, unsigned char *buffer, size_t
1349 buffer_size)
1350 size_t cbor_encode_break(unsigned char *buffer, size_t buffer_size)
1352 size_t cbor_encode_ctrl(uint8_t value, unsigned char *buffer, size_t
1354 buffer_size)
1355 Types 0 & 1 – Positive and negative integers
1357 CBOR has two types of integers – positive (which may be effectively re‐
1358 garded as unsigned), and negative. There are four possible widths for
1359 an integer – 1, 2, 4, or 8 bytes. These are represented by
1360 enum cbor_int_width
1362 Possible widths of CBOR_TYPE_UINT items.
1363 Values:
1365 enumerator CBOR_INT_8
1367 enumerator CBOR_INT_16
1369 enumerator CBOR_INT_32
1371 enumerator CBOR_INT_64
1373 Type 0 - positive integers
1375 ┌────────────────────────┬────────────────────────────┐
1376 │Corresponding cbor_type │ CBOR_TYPE_UINT │
1377 ├────────────────────────┼────────────────────────────┤
1378 │Number of allocations │ One per lifetime │
1379 ├────────────────────────┼────────────────────────────┤
1380 │Storage requirements │ sizeof(cbor_item_t) + │
1381 │ │ sizeof(uint*_t) │
1382 └────────────────────────┴────────────────────────────┘
1383 Note: once a positive integer has been created, its width cannot be
1385 changed.
1386 Type 1 - negative integers
1388 ┌────────────────────────┬────────────────────────────┐
1389 │Corresponding cbor_type │ CBOR_TYPE_NEGINT │
1390 ├────────────────────────┼────────────────────────────┤
1391 │Number of allocations │ One per lifetime │
1392 ├────────────────────────┼────────────────────────────┤
1393 │Storage requirements │ sizeof(cbor_item_t) + │
1394 │ │ sizeof(uint*_t) │
1395 └────────────────────────┴────────────────────────────┘
1396 Note: once a positive integer has been created, its width cannot be
1398 changed.
1399 Type 0 & 1
1401 Due to their largely similar semantics, the following functions can be
1402 used for both Type 0 and Type 1 items. One can convert between them
1403 freely using the conversion functions.
1404 Actual Type of the integer can be checked using item types API.
1406 An integer item is created with one of the four widths. Because inte‐
1408 gers' storage is bundled together with the handle, the width cannot be
1409 changed over its lifetime.
1410 WARNING:
1412 Due to the fact that CBOR negative integers represent integers in
1413 the range [-1, -2^N], cbor_set_uint API is somewhat counter-intu‐
1414 itive as the resulting logical value is 1 less. This behavior is
1415 necessary in order to permit uniform manipulation with the full
1416 range of permitted values. For example, the following snippet
1417 cbor_item_t * item = cbor_new_int8();
1419 cbor_mark_negint(item);
1420 cbor_set_uint8(0);
1421 will produce an item with the logical value of -1. There is, how‐
1423 ever, an upside to this as well: There is only one representation of
1424 zero.
1425 Building new items
1427 cbor_item_t *cbor_build_uint8(uint8_t value)
1428 Constructs a new positive integer.
1429 param value
1431 the value to use
1432 return new positive integer or NULL on memory allocation failure
1434 cbor_item_t *cbor_build_uint16(uint16_t value)
1436 Constructs a new positive integer.
1437 param value
1439 the value to use
1440 return new positive integer or NULL on memory allocation failure
1442 cbor_item_t *cbor_build_uint32(uint32_t value)
1444 Constructs a new positive integer.
1445 param value
1447 the value to use
1448 return new positive integer or NULL on memory allocation failure
1450 cbor_item_t *cbor_build_uint64(uint64_t value)
1452 Constructs a new positive integer.
1453 param value
1455 the value to use
1456 return new positive integer or NULL on memory allocation failure
1458 Retrieving values
1460 uint8_t cbor_get_uint8(const cbor_item_t *item)
1461 Extracts the integer value.
1462 param item
1464 positive or negative integer
1465 return the value
1467 uint16_t cbor_get_uint16(const cbor_item_t *item)
1469 Extracts the integer value.
1470 param item
1472 positive or negative integer
1473 return the value
1475 uint32_t cbor_get_uint32(const cbor_item_t *item)
1477 Extracts the integer value.
1478 param item
1480 positive or negative integer
1481 return the value
1483 uint64_t cbor_get_uint64(const cbor_item_t *item)
1485 Extracts the integer value.
1486 param item
1488 positive or negative integer
1489 return the value
1491 Setting values
1493 void cbor_set_uint8(cbor_item_t *item, uint8_t value)
1494 Assigns the integer value.
1495 param item
1497 positive or negative integer item
1498 param value
1500 the value to assign. For negative integer, the logical
1501 value is -value - 1
1502 void cbor_set_uint16(cbor_item_t *item, uint16_t value)
1504 Assigns the integer value.
1505 param item
1507 positive or negative integer item
1508 param value
1510 the value to assign. For negative integer, the logical
1511 value is -value - 1
1512 void cbor_set_uint32(cbor_item_t *item, uint32_t value)
1514 Assigns the integer value.
1515 param item
1517 positive or negative integer item
1518 param value
1520 the value to assign. For negative integer, the logical
1521 value is -value - 1
1522 void cbor_set_uint64(cbor_item_t *item, uint64_t value)
1524 Assigns the integer value.
1525 param item
1527 positive or negative integer item
1528 param value
1530 the value to assign. For negative integer, the logical
1531 value is -value - 1
1532 Dealing with width
1534 cbor_int_width cbor_int_get_width(const cbor_item_t *item)
1535 Queries the integer width.
1536 param item
1538 positive or negative integer item
1539 return the width
1541 Dealing with signedness
1543 void cbor_mark_uint(cbor_item_t *item)
1544 Marks the integer item as a positive integer.
1545 The data value is not changed
1547 param item
1549 positive or negative integer item
1550 void cbor_mark_negint(cbor_item_t *item)
1552 Marks the integer item as a negative integer.
1553 The data value is not changed
1555 param item
1557 positive or negative integer item
1558 Creating new items
1560 cbor_item_t *cbor_new_int8(void)
1561 Allocates new integer with 1B width.
1562 The width cannot be changed once allocated
1564 return new positive integer or NULL on memory allocation fail‐
1566 ure. The value is not initialized
1567 cbor_item_t *cbor_new_int16(void)
1569 Allocates new integer with 2B width.
1570 The width cannot be changed once allocated
1572 return new positive integer or NULL on memory allocation fail‐
1574 ure. The value is not initialized
1575 cbor_item_t *cbor_new_int32(void)
1577 Allocates new integer with 4B width.
1578 The width cannot be changed once allocated
1580 return new positive integer or NULL on memory allocation fail‐
1582 ure. The value is not initialized
1583 cbor_item_t *cbor_new_int64(void)
1585 Allocates new integer with 8B width.
1586 The width cannot be changed once allocated
1588 return new positive integer or NULL on memory allocation fail‐
1590 ure. The value is not initialized
1591 Type 2 – Byte strings
1593 CBOR byte strings are just (ordered) series of bytes without further
1594 interpretation (unless there is a tag). Byte string's length may or may
1595 not be known during encoding. These two kinds of byte strings can be
1596 distinguished using cbor_bytestring_is_definite() and
1597 cbor_bytestring_is_indefinite() respectively.
1598 In case a byte string is indefinite, it is encoded as a series of defi‐
1600 nite byte strings. These are called "chunks". For example, the encoded
1601 item
1602 0xf5 Start indefinite byte string
1604 0x41 Byte string (1B long)
1605 0x00
1606 0x41 Byte string (1B long)
1607 0xff
1608 0xff "Break" control token
1609 represents two bytes, 0x00 and 0xff. This on one hand enables streaming
1611 messages even before they are fully generated, but on the other hand it
1612 adds more complexity to the client code.
1613 ┌───────────────────────────┬────────────────────────────┐
1615 │Corresponding cbor_type │ CBOR_TYPE_BYTESTRING │
1616 ├───────────────────────────┼────────────────────────────┤
1617 │Number of allocations │ One plus any manipulations │
1618 │(definite) │ with the data │
1619 ├───────────────────────────┼────────────────────────────┤
1620 │Number of allocations (in‐ │ One plus logarithmically │
1621 │definite) │ many reallocations rela‐ │
1622 │ │ tive to chunk count │
1623 ├───────────────────────────┼────────────────────────────┤
1624 │Storage requirements (def‐ │ sizeof(cbor_item_t) + │
1625 │inite) │ length(handle) │
1626 ├───────────────────────────┼────────────────────────────┤
1627 │Storage requirements (in‐ │ sizeof(cbor_item_t) * (1 + │
1628 │definite) │ chunk_count) + chunks │
1629 └───────────────────────────┴────────────────────────────┘
1630 Getting metadata
1632 size_t cbor_bytestring_length(const cbor_item_t *item)
1633 Returns the length of the binary data.
1634 For definite byte strings only
1636 param item
1638 a definite bytestring
1639 return length of the binary data. Zero if no chunk has been at‐
1641 tached yet
1642 bool cbor_bytestring_is_definite(const cbor_item_t *item)
1644 Is the byte string definite?
1645 param item
1647 a byte string
1648 return Is the byte string definite?
1650 bool cbor_bytestring_is_indefinite(const cbor_item_t *item)
1652 Is the byte string indefinite?
1653 param item
1655 a byte string
1656 return Is the byte string indefinite?
1658 size_t cbor_bytestring_chunk_count(const cbor_item_t *item)
1660 Get the number of chunks this string consist of.
1661 param item
1663 A indefinite bytestring
1664 return The chunk count. 0 for freshly created items.
1666 Reading data
1668 cbor_mutable_data cbor_bytestring_handle(const cbor_item_t *item)
1669 Get the handle to the binary data.
1670 Definite items only. Modifying the data is allowed. In that
1672 case, the caller takes responsibility for the effect on items
1673 this item might be a part of
1674 param item
1676 A definite byte string
1677 return The address of the underlying binary data
1679 return NULL if no data have been assigned yet.
1681 cbor_item_t **cbor_bytestring_chunks_handle(const cbor_item_t *item)
1683 Get the handle to the array of chunks.
1684 Manipulations with the memory block (e.g. sorting it) are al‐
1686 lowed, but the validity and the number of chunks must be re‐
1687 tained.
1688 param item
1690 A indefinite byte string
1691 return array of cbor_bytestring_chunk_count definite bytestrings
1693 Creating new items
1695 cbor_item_t *cbor_new_definite_bytestring(void)
1696 Creates a new definite byte string.
1697 The handle is initialized to NULL and length to 0
1699 return Reference to the new bytestring item. The item's refer‐
1701 ence count is initialized to one.
1702 return NULL if memory allocation fails
1704 cbor_item_t *cbor_new_indefinite_bytestring(void)
1706 Creates a new indefinite byte string.
1707 The chunks array is initialized to NULL and chunk count to 0
1709 return Reference to the new bytestring item. The item's refer‐
1711 ence count is initialized to one.
1712 return NULL if memory allocation fails
1714 Building items
1716 cbor_item_t *cbor_build_bytestring(cbor_data handle, size_t length)
1717 Creates a new byte string and initializes it.
1718 The handle will be copied to a newly allocated block
1720 param handle
1722 Block of binary data
1723 param length
1725 Length of data
1726 return Reference to the new bytestring item. The item's refer‐
1728 ence count is initialized to one.
1729 return NULL if memory allocation fails
1731 Manipulating existing items
1733 void cbor_bytestring_set_handle(cbor_item_t *item, cbor_mutable_data
1734 data, size_t length)
1735 Set the handle to the binary data.
1736 param item
1738 A definite byte string
1739 param data
1741 The memory block. The caller gives up the ownership of
1742 the block. libcbor will deallocate it when appropriate
1743 using the free implementation configured using
1744 cbor_set_allocs
1745 param length
1747 Length of the data block
1748 bool cbor_bytestring_add_chunk(cbor_item_t *item, cbor_item_t *chunk)
1750 Appends a chunk to the bytestring.
1751 Indefinite byte strings only.
1753 May realloc the chunk storage.
1755 param item
1757 An indefinite byte string
1758 param chunk
1760 A definite byte string. Its reference count will be be
1761 increased by one.
1762 return true on success, false on realloc failure. In that case,
1764 the refcount of chunk is not increased and the item is
1765 left intact.
1766 Type 3 – UTF-8 strings
1768 CBOR strings have the same structure as Type 2 – Byte strings.
1769 ┌───────────────────────────┬────────────────────────────┐
1771 │Corresponding cbor_type │ CBOR_TYPE_STRING │
1772 ├───────────────────────────┼────────────────────────────┤
1773 │Number of allocations │ One plus any manipulations │
1774 │(definite) │ with the data │
1775 ├───────────────────────────┼────────────────────────────┤
1776 │Number of allocations (in‐ │ One plus logarithmically │
1777 │definite) │ many reallocations rela‐ │
1778 │ │ tive to chunk count │
1779 ├───────────────────────────┼────────────────────────────┤
1780 │Storage requirements (def‐ │ sizeof(cbor_item_t) + │
1781 │inite) │ length(handle) │
1782 ├───────────────────────────┼────────────────────────────┤
1783 │Storage requirements (in‐ │ sizeof(cbor_item_t) * (1 + │
1784 │definite) │ chunk_count) + chunks │
1785 └───────────────────────────┴────────────────────────────┘
1786 UTF-8 encoding validation
1788 libcbor considers UTF-8 encoding validity to be a part of the
1789 well-formedness notion of CBOR and therefore invalid UTF-8 strings will
1790 be rejected by the parser. Strings created by the user are not checked.
1791 Getting metadata
1793 size_t cbor_string_length(const cbor_item_t *item)
1794 Returns the length of the underlying string in bytes.
1795 There can be fewer unicode character than bytes (see
1797 cbor_string_codepoint_count). For definite strings only.
1798 param item
1800 a definite string
1801 return length of the string. Zero if no chunk has been attached
1803 yet
1804 bool cbor_string_is_definite(const cbor_item_t *item)
1806 Is the string definite?
1807 param item
1809 a string
1810 return Is the string definite?
1812 bool cbor_string_is_indefinite(const cbor_item_t *item)
1814 Is the string indefinite?
1815 param item
1817 a string
1818 return Is the string indefinite?
1820 size_t cbor_string_chunk_count(const cbor_item_t *item)
1822 Get the number of chunks this string consist of.
1823 param item
1825 A indefinite string
1826 return The chunk count. 0 for freshly created items.
1828 Reading data
1830 cbor_mutable_data cbor_string_handle(const cbor_item_t *item)
1831 Get the handle to the underlying string.
1832 Definite items only. Modifying the data is allowed. In that
1834 case, the caller takes responsibility for the effect on items
1835 this item might be a part of
1836 param item
1838 A definite string
1839 return The address of the underlying string.
1841 return NULL if no data have been assigned yet.
1843 cbor_item_t **cbor_string_chunks_handle(const cbor_item_t *item)
1845 Get the handle to the array of chunks.
1846 Manipulations with the memory block (e.g. sorting it) are al‐
1848 lowed, but the validity and the number of chunks must be re‐
1849 tained.
1850 param item
1852 A indefinite string
1853 return array of cbor_string_chunk_count definite strings
1855 Creating new items
1857 cbor_item_t *cbor_new_definite_string(void)
1858 Creates a new definite string.
1859 The handle is initialized to NULL and length to 0
1861 return Reference to the new string item. The item's reference
1863 count is initialized to one.
1864 return NULL if memory allocation fails
1866 cbor_item_t *cbor_new_indefinite_string(void)
1868 Creates a new indefinite string.
1869 The chunks array is initialized to NULL and chunkcount to 0
1871 return Reference to the new string item. The item's reference
1873 count is initialized to one.
1874 return NULL if memory allocation fails
1876 Building items
1878 cbor_item_t *cbor_build_string(const char *val)
1879 Creates a new string and initializes it.
1880 The val will be copied to a newly allocated block
1882 param val
1884 A null-terminated UTF-8 string
1885 return Reference to the new string item. The item's reference
1887 count is initialized to one.
1888 return NULL if memory allocation fails
1890 Manipulating existing items
1892 void cbor_string_set_handle(cbor_item_t *item, cbor_mutable_data data,
1893 size_t length)
1894 Set the handle to the underlying string.
1895 WARNING:
1897 Using a pointer to a stack allocated constant is a common
1898 mistake. Lifetime of the string will expire when it goes out
1899 of scope and the CBOR item will be left inconsistent.
1900 param item
1902 A definite string
1903 param data
1905 The memory block. The caller gives up the ownership of
1906 the block. libcbor will deallocate it when appropriate
1907 using its free function
1908 param length
1910 Length of the data block
1911 bool cbor_string_add_chunk(cbor_item_t *item, cbor_item_t *chunk)
1913 Appends a chunk to the string.
1914 Indefinite strings only.
1916 May realloc the chunk storage.
1918 param item
1920 An indefinite string
1921 param chunk
1923 A definite string item. Its reference count will be in‐
1924 creased by one.
1925 return true on success. false on memory allocation failure. In
1927 that case, the refcount of `chunk` is not increased and
1928 the `item` is left intact.
1929 Type 4 – Arrays
1931 CBOR arrays, just like byte strings and strings, can be encoded either
1932 as definite, or as indefinite. Definite arrays have a fixed size which
1933 is stored in the header, whereas indefinite arrays do not and are ter‐
1934 minated by a special "break" byte instead.
1935 Arrays are explicitly created or decoded as definite or indefinite and
1937 will be encoded using the corresponding wire representation, regardless
1938 of whether the actual size is known at the time of encoding.
1939 NOTE:
1941 Indefinite arrays can be conveniently used with streaming decoding
1942 and encoding.
1943 ┌───────────────────────────┬────────────────────────────┐
1945 │Corresponding cbor_type │ CBOR_TYPE_ARRAY │
1946 ├───────────────────────────┼────────────────────────────┤
1947 │Number of allocations │ Two plus any manipulations │
1948 │(definite) │ with the data │
1949 ├───────────────────────────┼────────────────────────────┤
1950 │Number of allocations (in‐ │ Two plus logarithmically │
1951 │definite) │ many reallocations rela‐ │
1952 │ │ tive to additions │
1953 ├───────────────────────────┼────────────────────────────┤
1954 │Storage requirements (def‐ │ (sizeof(cbor_item_t) + 1) │
1955 │inite) │ * size │
1956 ├───────────────────────────┼────────────────────────────┤
1957 │Storage requirements (in‐ │ <= sizeof(cbor_item_t) + │
1958 │definite) │ sizeof(cbor_item_t) * size │
1959 │ │ * BUFFER_GROWTH │
1960 └───────────────────────────┴────────────────────────────┘
1961 Examples
1963 0x9f Start indefinite array
1964 0x01 Unsigned integer 1
1965 0xff "Break" control token
1966 0x9f Start array, 1B length follows
1968 0x20 Unsigned integer 32
1969 ... 32 items follow
1970 Getting metadata
1972 size_t cbor_array_size(const cbor_item_t *item)
1973 Get the number of members.
1974 param item
1976 An array
1977 return The number of members
1979 size_t cbor_array_allocated(const cbor_item_t *item)
1981 Get the size of the allocated storage.
1982 param item
1984 An array
1985 return The size of the allocated storage (number of items)
1987 bool cbor_array_is_definite(const cbor_item_t *item)
1989 Is the array definite?
1990 param item
1992 An array
1993 return Is the array definite?
1995 bool cbor_array_is_indefinite(const cbor_item_t *item)
1997 Is the array indefinite?
1998 param item
2000 An array
2001 return Is the array indefinite?
2003 Reading data
2005 cbor_item_t **cbor_array_handle(const cbor_item_t *item)
2006 Get the array contents.
2007 The items may be reordered and modified as long as references
2009 remain consistent.
2010 param item
2012 An array item
2013 return An array of cbor_item_t pointers of size cbor_array_size.
2015 cbor_item_t *cbor_array_get(const cbor_item_t *item, size_t index)
2017 Get item by index.
2018 Increases the reference count of the underlying item. The re‐
2021 turned reference must be released using cbor_decref.
2022 param item
2024 An array
2025 param index
2027 The index (zero-based)
2028 return Reference to the item, or NULL in case of boundary viola‐
2030 tion.
2031 Creating new items
2033 cbor_item_t *cbor_new_definite_array(size_t size)
2034 Create new definite array.
2035 param size
2037 Number of slots to preallocate
2038 return Reference to the new array item. The item's reference
2040 count is initialized to one.
2041 return NULL if memory allocation fails
2043 cbor_item_t *cbor_new_indefinite_array(void)
2045 Create new indefinite array.
2046 return Reference to the new array item. The item's reference
2048 count is initialized to one.
2049 return NULL if memory allocation fails
2051 Modifying items
2053 bool cbor_array_push(cbor_item_t *array, cbor_item_t *pushee)
2054 Append to the end.
2055 For indefinite items, storage may be reallocated. For definite
2057 items, only the preallocated capacity is available.
2058 param array
2060 An array
2061 param pushee
2063 The item to push. Its reference count will be increased
2064 by one.
2065 return true on success, false on failure
2067 bool cbor_array_replace(cbor_item_t *item, size_t index, cbor_item_t
2069 *value)
2070 Replace item at an index.
2071 The reference to the item being replaced will be released using
2073 cbor_decref.
2074 param item
2076 An array
2077 param value
2079 The item to assign. Its reference count will be increased
2080 by one.
2081 param index
2083 The index (zero-based)
2084 return true on success, false on allocation failure.
2086 bool cbor_array_set(cbor_item_t *item, size_t index, cbor_item_t
2088 *value)
2089 Set item by index.
2090 If the index is out of bounds, the array is not modified and
2092 false is returned. Creating arrays with holes is not possible.
2093 param item
2095 An array
2096 param value
2098 The item to assign
2099 param index
2101 The index (zero-based)
2102 return true on success, false on allocation failure.
2104 Type 5 – Maps
2106 CBOR maps are the plain old associative maps similar JSON objects or
2107 Python dictionaries.
2108 Definite maps have a fixed size which is stored in the header, whereas
2110 indefinite maps do not and are terminated by a special "break" byte in‐
2111 stead.
2112 Map are explicitly created or decoded as definite or indefinite and
2114 will be encoded using the corresponding wire representation, regardless
2115 of whether the actual size is known at the time of encoding.
2116 NOTE:
2118 Indefinite maps can be conveniently used with streaming decoding and
2119 encoding. Keys and values can simply be output one by one, alter‐
2120 nating keys and values.
2121 WARNING:
2123 Any CBOR data item is a legal map key (not just strings).
2124 ┌───────────────────────────┬────────────────────────────┐
2126 │Corresponding cbor_type │ CBOR_TYPE_MAP │
2127 ├───────────────────────────┼────────────────────────────┤
2128 │Number of allocations │ Two plus any manipulations │
2129 │(definite) │ with the data │
2130 ├───────────────────────────┼────────────────────────────┤
2131 │Number of allocations (in‐ │ Two plus logarithmically │
2132 │definite) │ many reallocations rela‐ │
2133 │ │ tive to additions │
2134 ├───────────────────────────┼────────────────────────────┤
2135 │Storage requirements (def‐ │ sizeof(cbor_pair) * size + │
2136 │inite) │ sizeof(cbor_item_t) │
2137 ├───────────────────────────┼────────────────────────────┤
2138 │Storage requirements (in‐ │ <= sizeof(cbor_item_t) + │
2139 │definite) │ sizeof(cbor_pair) * size * │
2140 │ │ BUFFER_GROWTH │
2141 └───────────────────────────┴────────────────────────────┘
2142 Examples
2144 0xbf Start indefinite map (represents {1: 2})
2145 0x01 Unsigned integer 1 (key)
2146 0x02 Unsigned integer 2 (value)
2147 0xff "Break" control token
2148 0xa0 Map of size 0
2150 Getting metadata
2152 size_t cbor_map_size(const cbor_item_t *item)
2153 Get the number of pairs.
2154 param item
2156 A map
2157 return The number of pairs
2159 size_t cbor_map_allocated(const cbor_item_t *item)
2161 Get the size of the allocated storage.
2162 param item
2164 A map
2165 return Allocated storage size (as the number of cbor_pair items)
2167 bool cbor_map_is_definite(const cbor_item_t *item)
2169 Is this map definite?
2170 param item
2172 A map
2173 return Is this map definite?
2175 bool cbor_map_is_indefinite(const cbor_item_t *item)
2177 Is this map indefinite?
2178 param item
2180 A map
2181 return Is this map indefinite?
2183 Reading data
2185 struct cbor_pair *cbor_map_handle(const cbor_item_t *item)
2186 Get the pairs storage.
2187 param item
2189 A map
2190 return Array of cbor_map_size pairs. Manipulation is possible as
2192 long as references remain valid.
2193 Creating new items
2195 cbor_item_t *cbor_new_definite_map(size_t size)
2196 Create a new definite map.
2197 param size
2199 The number of slots to preallocate
2200 return Reference to the new map item. The item's reference count
2202 is initialized to one.
2203 return NULL if memory allocation fails
2205 cbor_item_t *cbor_new_indefinite_map(void)
2207 Create a new indefinite map.
2208 return Reference to the new map item. The item's reference count
2210 is initialized to one.
2211 return NULL if memory allocation fails
2213 Modifying items
2215 bool cbor_map_add(cbor_item_t *item, struct cbor_pair pair)
2216 Add a pair to the map.
2217 For definite maps, items can only be added to the preallocated
2219 space. For indefinite maps, the storage will be expanded as
2220 needed
2221 param item
2223 A map
2224 param pair
2226 The key-value pair to add. Reference count of the
2227 cbor_pair.key and cbor_pair.value will be increased by
2228 one.
2229 return true on success, false if memory allocation failed (in‐
2231 definite maps) or the preallocated storage is full (defi‐
2232 nite maps)
2233 Type 6 – Semantic tags
2235 Tag are additional metadata that can be used to extend or specialize
2236 the meaning or interpretation of the other data items.
2237 For example, one might tag an array of numbers to communicate that it
2239 should be interpreted as a vector.
2240 Please consult the official IANA repository of CBOR tags before invent‐
2242 ing new ones.
2243 ┌────────────────────────┬────────────────────────────┐
2245 │Corresponding cbor_type │ CBOR_TYPE_TAG │
2246 ├────────────────────────┼────────────────────────────┤
2247 │Number of allocations │ One plus any manipulations │
2248 │ │ with the data realloca‐ │
2249 │ │ tions relative to chunk │
2250 │ │ count │
2251 ├────────────────────────┼────────────────────────────┤
2252 │Storage requirements │ sizeof(cbor_item_t) + the │
2253 │ │ tagged item │
2254 └────────────────────────┴────────────────────────────┘
2255 cbor_item_t *cbor_new_tag(uint64_t value)
2257 Create a new tag.
2258 param value
2260 The tag value. Please consult the tag repository
2261 return Reference to the new tag item. The item's reference count
2263 is initialized to one.
2264 return NULL if memory allocation fails
2266 cbor_item_t *cbor_tag_item(const cbor_item_t *item)
2268 Get the tagged item.
2269 Increases the reference count of the underlying item. The re‐
2272 turned reference must be released using cbor_decref.
2273 param item
2275 A tag
2276 return Reference to the tagged item
2278 uint64_t cbor_tag_value(const cbor_item_t *item)
2280 Get tag value.
2281 param item
2283 A tag
2284 return The tag value. Please consult the tag repository
2286 void cbor_tag_set_item(cbor_item_t *item, cbor_item_t *tagged_item)
2288 Set the tagged item.
2289 param item
2291 A tag
2292 param tagged_item
2294 The item to tag. Its reference count will be increased by
2295 one.
2296 Type 7 – Floats & control tokens
2298 This type combines two completely unrelated types of items -- floating
2299 point numbers and special values such as true, false, null, etc. We re‐
2300 fer to these special values as 'control values' or 'ctrls' for short
2301 throughout the code.
2302 Just like integers, they have different possible width (resulting in
2304 different value ranges and precisions).
2305 enum cbor_float_width
2307 Possible widths of CBOR_TYPE_FLOAT_CTRL items.
2308 Values:
2310 enumerator CBOR_FLOAT_0
2312 Internal use - ctrl and special values.
2313 enumerator CBOR_FLOAT_16
2315 Half float.
2316 enumerator CBOR_FLOAT_32
2318 Single float.
2319 enumerator CBOR_FLOAT_64
2321 Double.
2322 ┌────────────────────────┬────────────────────────────┐
2324 │Corresponding cbor_type │ CBOR_TYPE_FLOAT_CTRL │
2325 ├────────────────────────┼────────────────────────────┤
2326 │Number of allocations │ One per lifetime │
2327 ├────────────────────────┼────────────────────────────┤
2328 │Storage requirements │ sizeof(cbor_item_t) + │
2329 │ │ 1/4/8 │
2330 └────────────────────────┴────────────────────────────┘
2331 Getting metadata
2333 bool cbor_float_ctrl_is_ctrl(const cbor_item_t *item)
2334 Is this a ctrl value?
2335 param item
2337 A float or ctrl item
2338 return Is this a ctrl value?
2340 cbor_float_width cbor_float_get_width(const cbor_item_t *item)
2342 Get the float width.
2343 param item
2345 A float or ctrl item
2346 return The width.
2348 Reading data
2350 float cbor_float_get_float2(const cbor_item_t *item)
2351 Get a half precision float.
2352 The item must have the corresponding width
2354 param item
2356 A half precision float
2357 return half precision value
2359 float cbor_float_get_float4(const cbor_item_t *item)
2361 Get a single precision float.
2362 The item must have the corresponding width
2364 param item
2366 A single precision float
2367 return single precision value
2369 double cbor_float_get_float8(const cbor_item_t *item)
2371 Get a double precision float.
2372 The item must have the corresponding width
2374 param item
2376 A double precision float
2377 return double precision value
2379 double cbor_float_get_float(const cbor_item_t *item)
2381 Get the float value represented as double.
2382 Can be used regardless of the width.
2384 param item
2386 Any float
2387 return double precision value
2389 uint8_t cbor_ctrl_value(const cbor_item_t *item)
2391 Reads the control value.
2392 param item
2394 A ctrl item
2395 return the simple value
2397 bool cbor_get_bool(const cbor_item_t *item)
2399 Get value from a boolean ctrl item.
2400 param item
2402 A ctrl item
2403 return boolean value
2405 Creating new items
2407 cbor_item_t *cbor_new_ctrl(void)
2408 Constructs a new ctrl item.
2409 The width cannot be changed once the item is created
2411 return Reference to the new ctrl item. The item's reference
2413 count is initialized to one.
2414 return NULL if memory allocation fails
2416 cbor_item_t *cbor_new_float2(void)
2418 Constructs a new float item.
2419 The width cannot be changed once the item is created
2421 return Reference to the new float item. The item's reference
2423 count is initialized to one.
2424 return NULL if memory allocation fails
2426 cbor_item_t *cbor_new_float4(void)
2428 Constructs a new float item.
2429 The width cannot be changed once the item is created
2431 return Reference to the new float item. The item's reference
2433 count is initialized to one.
2434 return NULL if memory allocation fails
2436 cbor_item_t *cbor_new_float8(void)
2438 Constructs a new float item.
2439 The width cannot be changed once the item is created
2441 return Reference to the new float item. The item's reference
2443 count is initialized to one.
2444 return NULL if memory allocation fails
2446 cbor_item_t *cbor_new_null(void)
2448 Constructs new null ctrl item.
2449 return Reference to the new null item. The item's reference
2451 count is initialized to one.
2452 return NULL if memory allocation fails
2454 cbor_item_t *cbor_new_undef(void)
2456 Constructs new undef ctrl item.
2457 return Reference to the new undef item. The item's reference
2459 count is initialized to one.
2460 return NULL if memory allocation fails
2462 Building items
2464 cbor_item_t *cbor_build_bool(bool value)
2465 Constructs new boolean ctrl item.
2466 param value
2468 The value to use
2469 return Reference to the new boolean item. The item's reference
2471 count is initialized to one.
2472 return NULL if memory allocation fails
2474 cbor_item_t *cbor_build_ctrl(uint8_t value)
2476 Constructs a ctrl item.
2477 param value
2479 the value to use
2480 return Reference to the new ctrl item. The item's reference
2482 count is initialized to one.
2483 return NULL if memory allocation fails
2485 cbor_item_t *cbor_build_float2(float value)
2487 Constructs a new float.
2488 param value
2490 the value to use
2491 return Reference to the new float item. The item's reference
2493 count is initialized to one.
2494 return NULL if memory allocation fails
2496 cbor_item_t *cbor_build_float4(float value)
2498 Constructs a new float.
2499 param value
2501 the value to use
2502 return Reference to the new float item. The item's reference
2504 count is initialized to one.
2505 return NULL if memory allocation fails
2507 cbor_item_t *cbor_build_float8(double value)
2509 Constructs a new float.
2510 param value
2512 the value to use
2513 return Reference to the new float item. The item's reference
2515 count is initialized to one.
2516 return NULL if memory allocation fails
2518 Manipulating existing items
2520 void cbor_set_ctrl(cbor_item_t *item, uint8_t value)
2521 Assign a control value.
2522 WARNING:
2524 It is possible to produce an invalid CBOR value by assigning
2525 a invalid value using this mechanism. Please consult the
2526 standard before use.
2527 param item
2529 A ctrl item
2530 param value
2532 The simple value to assign. Please consult the standard
2533 for allowed values
2534 void cbor_set_bool(cbor_item_t *item, bool value)
2536 Assign a boolean value to a boolean ctrl item.
2537 param item
2539 A ctrl item
2540 param value
2542 The simple value to assign.
2543 void cbor_set_float2(cbor_item_t *item, float value)
2545 Assigns a float value.
2546 param item
2548 A half precision float
2549 param value
2551 The value to assign
2552 void cbor_set_float4(cbor_item_t *item, float value)
2554 Assigns a float value.
2555 param item
2557 A single precision float
2558 param value
2560 The value to assign
2561 void cbor_set_float8(cbor_item_t *item, double value)
2563 Assigns a float value.
2564 param item
2566 A double precision float
2567 param value
2569 The value to assign
2570 Half floats
2572 CBOR supports two bytes wide ("half-precision") floats which are not
2573 supported by the C language. libcbor represents them using float
2574 <https://en.cppreference.com/w/c/language/type> values throughout the
2575 API. Encoding will be performed by cbor_encode_half(), which will han‐
2576 dle any values that cannot be represented as a half-float.
2577 [1] http://softwareengineering.vazexqi.com/files/pattern.html
2579 Tests
2581 Unit tests
2582 There is a comprehensive test suite employing CMocka. You can run all
2583 of them using ctest in the build directory. Individual tests are them‐
2584 selves runnable. Please refer to CTest documentation for detailed in‐
2585 formation on how to specify particular subset of tests.
2586 Testing for memory leaks
2588 Every release is tested for memory correctness. You can run these tests
2589 by passing the -T memcheck flag to ctest. [1]
2590 [1] Project should be configured with -DCMAKE_BUILD_TYPE=Debug to ob‐
2592 tain meaningful description of location of the leak. You might
2593 also need --dsymutil=yes on OS X.
2594 Code coverage
2596 Every release is inspected using GCOV/LCOV. Platform-independent code
2597 should be fully covered by the test suite. Simply run
2598 make coverage
2600 or alternatively run lcov by hand using
2602 lcov --capture --directory . --output-file coverage.info
2604 genhtml coverage.info --output-directory out
2605 Fuzz testing
2607 Every release is tested using a fuzz test. In this test, a huge buffer
2608 filled with random data is passed to the decoder. We require that it
2609 either succeeds or fail with a sensible error, without leaking any mem‐
2610 ory. This is intended to simulate real-world situations where data re‐
2611 ceived from the network are CBOR-decoded before any further processing.
2612 RFC conformance
2614 libcbor is, generally speaking, very faithful implementation of RFC
2615 7049. There are, however, some limitations imposed by technical con‐
2616 straints.
2617 Bytestring length
2619 There is no explicit limitation of indefinite length byte strings. [1]
2620 libcbor will not handle byte strings with more chunks than the maximum
2621 value of size_t. On any sane platform, such string would not fit in the
2622 memory anyway. It is, however, possible to process arbitrarily long
2623 strings and byte strings using the streaming decoder.
2624 [1] https://tools.ietf.org/html/rfc7049#section-2.2.2
2626 "Half-precision" IEEE 754 floats
2628 As of C99 and even C11, there is no standard implementation for 2 bytes
2629 floats. libcbor packs them as a float <https://en.cpprefer‐
2630 ence.com/w/c/language/type>. When encoding, libcbor selects the appro‐
2631 priate wire representation based on metadata and the actual value. This
2632 applies both to canonical and normal mode.
2633 For more information on half-float serialization, please refer to the
2635 section on Half floats.
2636 Internal mechanics
2638 Internal workings of libcbor are mostly derived from the specification.
2639 The purpose of this document is to describe technical choices made dur‐
2640 ing design & implementation and to explicate the reasoning behind those
2641 choices.
2642 Terminology
2644 ┌────┬─────────────────────┬────────────────────────────────────────────────┐
2645 │MTB │ Major Type Byte │ http://tools.ietf.org/html/rfc7049#section-2.1 │
2646 ├────┼─────────────────────┼────────────────────────────────────────────────┤
2647 │DST │ Dynamically Sized │ Type whose storage requirements cannot be de‐ │
2648 │ │ Type │ termined │
2649 │ │ │ │
2650 │ │ │ during compilation (originated in the Rust │
2651 │ │ │ community) │
2652 └────┴─────────────────────┴────────────────────────────────────────────────┘
2653 Conventions
2655 API symbols start with cbor_ or CBOR_ prefix, internal symbols have
2656 _cbor_ or _CBOR_ prefix.
2657 Inspiration & related projects
2659 Most of the API is largely modelled after existing JSON libraries, in‐
2660 cluding
2661 • Jansson
2663 • json-c
2665 • Gnome's JsonGlib
2667 and also borrowing from
2669 • msgpack-c
2671 • Google Protocol Buffers.
2673 General notes on the API design
2675 The API design has two main driving priciples:
2676 1. Let the client manage the memory as much as possible
2678 2. Behave exactly as specified by the standard
2680 Combining these two principles in practice turns out to be quite diffi‐
2682 cult. Indefinite-length strings, arrays, and maps require client to
2683 handle every fixed-size chunk explicitly in order to
2684 • ensure the client never runs out of memory due to libcbor
2686 • use realloc() sparsely and predictably [1]
2688 • provide strong guarantees about its usage (to prevent la‐
2690 tency spikes)
2691 • provide APIs to avoid realloc() altogether
2693 • allow proper handling of (streamed) data bigger than available
2695 memory
2696 [1] Reasonable handling of DSTs requires reallocation if the API is
2698 to remain sane.
2699 Coding style
2701 This code loosely follows the Linux kernel coding style. Tabs are tabs,
2702 and they are 4 characters wide.
2703 Memory layout
2705 CBOR is very dynamic in the sense that it contains many data elements
2706 of variable length, sometimes even indefinite length. This section de‐
2707 scribes internal representation of all CBOR data types.
2708 Generally speaking, data items consist of three parts:
2710 • a generic handle,
2712 • the associated metadata,
2714 • and the actual data
2716 type cbor_item_t
2718 Represents the item. Used as an opaque type
2719 cbor_type type
2721 Type discriminator
2722 size_t refcount
2724 Reference counter. Used by cbor_decref(), cbor_incref()
2725 union cbor_item_metadata metadata
2727 Union discriminated by type. Contains type-specific meta‐
2728 data
2729 unsigned char *data
2731 Contains pointer to the actual data. Small, fixed size
2732 items (Types 0 & 1 – Positive and negative integers, Type
2733 6 – Semantic tags, Type 7 – Floats & control tokens) are
2734 allocated as a single memory block.
2735 Consider the following snippet
2737 cbor_item_t * item = cbor_new_int8();
2739 then the memory is laid out as follows
2741 +-----------+---------------+---------------+-----------------------------------++-----------+
2743 | | | | || |
2744 | type | refcount | metadata | data || uint8_t |
2745 | | | | (= item + sizeof(cbor_item_t)) || |
2746 +-----------+---------------+---------------+-----------------------------------++-----------+
2747 ^ ^
2748 | |
2749 +--- item +--- item->data
2750 Dynamically sized types (Type 2 – Byte strings, Type 3 –
2752 UTF-8 strings, Type 4 – Arrays, Type 5 – Maps) may store
2753 handle and data in separate locations. This enables cre‐
2754 ating large items (e.g byte strings) without realloc() or
2755 copying large blocks of memory. One simply attaches the
2756 correct pointer to the handle.
2757 type cbor_item_metadata
2759 Union type of the following members, based on the item type:
2760 struct _cbor_int_metadata int_metadata
2762 Used both by both Types 0 & 1 – Positive and negative in‐
2763 tegers
2764 struct _cbor_bytestring_metadata bytestring_metadata
2766 struct _cbor_string_metadata string_metadata
2768 struct _cbor_array_metadata array_metadata
2770 struct _cbor_map_metadata map_metadata
2772 struct _cbor_tag_metadata tag_metadata
2774 struct _cbor_float_ctrl_metadata float_ctrl_metadata
2776 Decoding
2778 As outlined in API, there decoding is based on the streaming decoder
2779 Essentially, the decoder is a custom set of callbacks for the streaming
2780 decoder.
2781 Changelog
2783 Template: - [Fix issue X in feature Y](‐
2784 https://github.com/PJK/libcbor/pull/XXX) (by [YYY](‐
2785 https://github.com/YYY))
2786 Next
2788 0.10.2 (2023-01-31)
2789 • [Fixed minor test bug causing failures for x86 Linux](‐
2790 https://github.com/PJK/libcbor/pull/266) (discovered by [trofi](‐
2791 https://github.com/PJK/libcbor/issues/263)) - Actual libcbor func‐
2792 tionality not affected, bug was in the test suite
2793 • [Made tests platform-independent](‐
2795 https://github.com/PJK/libcbor/pull/272)
2796 0.10.1 (2022-12-30)
2798 • [Fix a regression in cbor_serialize_alloc that caused serialization
2799 of zero-length strings and bytestrings or byte/strings with
2800 zero-length chunks to fail](https://github.com/PJK/libcbor/pull/260)
2801 (discovered by [martelletto](https://github.com/martelletto))
2802 0.10.0 (2022-12-29)
2804 • Make the buffer_size optional in cbor_serialize_alloc [[#205]](‐
2805 https://github.com/PJK/libcbor/pull/205) (by [hughsie](‐
2806 https://github.com/hughsie))
2807 • BREAKING: Improved half-float encoding for denormalized numbers.
2809 [[#208]](https://github.com/PJK/libcbor/pull/208) (by [ranvis](‐
2810 https://github.com/ranvis)) - Denormalized half-floats will now pre‐
2811 serve data in the mantissa - Note: Half-float NaNs still lose data (‐
2812 https://github.com/PJK/libcbor/issues/215)
2813 • BUILD BREAKING: Minimum CMake version is 3.0 [[#201]](‐
2815 https://github.com/PJK/libcbor/pull/201) (by [thewtex@](‐
2816 https://github.com/thewtex)) - See
2817 https://repology.org/project/cmake/versions for support; the vast ma‐
2818 jority of users should not be affected.
2819 • Fix a potential memory leak when the allocator fails during array or
2821 map decoding [[#224]](https://github.com/PJK/libcbor/pull/224) (by
2822 [James-ZHANG](https://github.com/James-ZHANG))
2823 • [Fix a memory leak when the allocator fails when adding chunks to in‐
2825 definite bytestrings.](https://github.com/PJK/libcbor/pull/242)
2826 ([discovered](https://github.com/PJK/libcbor/pull/228) by
2827 [James-ZHANG](https://github.com/James-ZHANG))
2828 • [Fix a memory leak when the allocator fails when adding chunks to in‐
2830 definite strings](https://github.com/PJK/libcbor/pull/246)
2831 • Potentially BUILD BREAKING: [Add nodiscard attributes to most
2833 functions](https://github.com/PJK/libcbor/pull/248) - Warning: This
2834 may cause new build warnings and (in rare cases, depending on your
2835 configuration) errors
2836 • BREAKING: [Fix cbor_copy leaking memory and creating invalid items
2838 when the allocator fails](https://github.com/PJK/libcbor/pull/249).
2839 - Previously, the failures were not handled in the interface. Now,
2840 cbor_copy may return NULL upon failure; clients should check the re‐
2841 turn value
2842 • [Fix cbor_build_tag illegal memory behavior when the allocator
2844 fails](https://github.com/PJK/libcbor/pull/249)
2845 • [Add a new cbor_serialized_size API](‐
2847 https://github.com/PJK/libcbor/pull/250)
2848 • [Reworked cbor_serialize_alloc to allocate the exact amount of memory
2850 necessary upfront](https://github.com/PJK/libcbor/pull/251) - This
2851 should significantly speed up cbor_serialize_alloc for large items by
2852 avoiding multiple reallocation iterations - Clients should not use
2853 the return value of cbor_serialize_alloc. It may be removed in the
2854 future.
2855 • BUILD BREAKING: [Deprecate CBOR_CUSTOM_ALLOC](‐
2857 https://github.com/PJK/libcbor/pull/237) - cbor_set_allocs will al‐
2858 ways be enabled from now on - Note: The flag will be kept as a no-op
2859 triggering a warning when used for one version and then removed com‐
2860 pletely
2861 0.9.0 (2021-11-14)
2863 • Improved pkg-config paths handling [[#164]](‐
2864 https://github.com/PJK/libcbor/pull/164) (by [jtojnar@](‐
2865 https://github.com/jtojnar))
2866 • Use explicit math.h linkage [[#170]](‐
2868 https://github.com/PJK/libcbor/pull/170)
2869 •
2871 BREAKING: Fixed handling of items that exceed the host size_t range
2873 [[#186]](https://github.com/PJK/libcbor/pull/186hg)
2874 • Callbacks for bytestrings, strings, arrays, and maps use
2876 uint64_t instead of size_t to allow handling of large items
2877 that exceed size_t even if size_t < uint64_t
2878 • cbor_decode explicitly checks size to avoid overflows (pre‐
2880 viously broken, potentially resulting in erroneous decoding
2881 on affected systems)
2882 • The change should be a noop for 64b systems
2884 • Added a [Bazel](https://bazel.build/) build example [[#196]](‐
2886 https://github.com/PJK/libcbor/pull/196) (by [andyjgf@](‐
2887 https://github.com/andyjgf))
2888 0.8.0 (2020-09-20)
2890 • BUILD BREAKING: Use BUILD_SHARED_LIBS to determine how to build li‐
2891 braries (fixed Windows linkage) [[#148]](‐
2892 https://github.com/PJK/libcbor/pull/148) (by [intelligide@](‐
2893 https://github.com/intelligide))
2894 • BREAKING: Fix cbor_tag_item not increasing the reference count on the
2896 tagged item reference it returns [[Fixes #109](‐
2897 https://github.com/PJK/libcbor/issues/109)] (discovered bt
2898 [JohnGilmour](https://github.com/JohnGilmour)) - If you have previ‐
2899 ously relied on the broken behavior, you can use cbor_move to emulate
2900 as long as the returned handle is an "rvalue"
2901 •
2903 BREAKING: [CBOR_DECODER_EBUFFER removed from cbor_decoder_status](‐
2905 https://github.com/PJK/libcbor/pull/156)
2906 • cbor_stream_decode will set CBOR_DECODER_NEDATA instead if
2908 the input buffer is empty
2909 • [Fix cbor_stream_decode](https://github.com/PJK/libcbor/pull/156) to
2911 set cbor_decoder_result.required to the minimum number of input bytes
2912 necessary to receive the next callback (as long as at least one byte
2913 was passed) (discovered by [woefulwabbit](‐
2914 https://github.com/woefulwabbit))
2915 • Fixed several minor manpage issues [[#159]](‐
2917 https://github.com/PJK/libcbor/pull/159) (discovered by [kloczek@](‐
2918 https://github.com/kloczek))
2919 0.7.0 (2020-04-25)
2921 •
2922 Fix bad encoding of NaN half-floats [[Fixes #53]](‐
2924 https://github.com/PJK/libcbor/issues/53) (discovered by
2925 [BSipos-RKF](https://github.com/BSipos-RKF))
2926 • Warning: Previous versions encoded NaNs as 0xf9e700 instead
2928 of 0xf97e00; if you rely on the broken behavior, this will
2929 be a breaking change
2930 • Fix potentially bad encoding of negative half-float with exponent <
2932 -14 [[Fixes #112]](https://github.com/PJK/libcbor/issues/112) (dis‐
2933 covered by [yami36](https://github.com/yami36))
2934 •
2936 BREAKING: Improved bool support [[Fixes #63]](‐
2938 https://github.com/PJK/libcbor/issues/63)
2939 • Rename cbor_ctrl_is_bool to cbor_get_bool and fix the behav‐
2941 ior
2942 • Add cbor_set_bool
2944 • Fix memory_allocation_test breaking the build without CBOR_CUSTOM_AL‐
2946 LOC [[Fixes #128]](https://github.com/PJK/libcbor/issues/128) (by
2947 [panlinux](https://github.com/panlinux))
2948 • [Fix a potential build issue where cJSON includes may be
2950 misconfigured](https://github.com/PJK/libcbor/pull/132)
2951 •
2953 Breaking: [Add a limit on the size of the decoding context stack](‐
2955 https://github.com/PJK/libcbor/pull/138) (by [James-ZHANG](‐
2956 https://github.com/James-ZHANG))
2957 • If your usecase requires parsing very deeply nested struc‐
2959 tures, you might need to increase the default 2k limit via
2960 CBOR_MAX_STACK_SIZE
2961 •
2963 Enable LTO/IPO based on [CheckIPOSupported](‐
2965 https://cmake.org/cmake/help/latest/module/CheckIPOSup‐
2966 ported.html#module:CheckIPOSupported) [[#143]](‐
2967 https://github.com/PJK/libcbor/pull/143) (by [xanderlent](‐
2968 https://github.com/xanderlent))
2969 • If you rely on LTO being enabled and use CMake version older
2971 than 3.9, you will need to re-enable it manually or upgrade
2972 your CMake
2973 0.6.1 (2020-03-26)
2975 •
2976 [Fix bad shared library version number](‐
2978 https://github.com/PJK/libcbor/pull/131)
2979 • Warning: Shared library built from the 0.6.0 release is er‐
2981 roneously marked as version "0.6.0", which makes it incom‐
2982 patible with future releases including the v0.6.X line even
2983 though they may be compatible API/ABI-wise. Refer to the
2984 documentation for the new SO versioning scheme.
2985 0.6.0 (2020-03-15)
2987 •
2988 Correctly set .so version [[Fixes #52]](‐
2990 https://github.com/PJK/libcbor/issues/52).
2991 • Warning: All previous releases will be identified as 0.0 by
2993 the linker.
2994 • Fix & prevent heap overflow error in example code [[#74]](‐
2996 https://github.com/PJK/libcbor/pull/74) [[#76]](‐
2997 https://github.com/PJK/libcbor/pull/76) (by @nevun)
2998 • Correctly set OSX dynamic library version [[Fixes #75]](‐
3000 https://github.com/PJK/libcbor/issues/75)
3001 • [Fix misplaced 0xFF bytes in maps possibly causing memory
3003 corruption](https://github.com/PJK/libcbor/pull/82)
3004 • BREAKING: Fix handling & cleanup of failed memory allocation in con‐
3006 structor and builder helper functions [[Fixes #84]](‐
3007 https://github.com/PJK/libcbor/issues/84) - All cbor_new_* and
3008 cbor_build_* functions will now explicitly return NULL when memory
3009 allocation fails - It is up to the client to handle such cases
3010 • Globally enforced code style [[Fixes #83]](‐
3012 https://github.com/PJK/libcbor/issues/83)
3013 • Fix issue possible memory corruption bug on repeated
3015 cbor_(byte)string_add_chunk calls with intermittently failing realloc
3016 calls
3017 • Fix possibly misaligned reads and writes when endian.h is uses or
3019 when running on a big-endian machine [[Fixes #99](‐
3020 https://github.com/PJK/libcbor/issues/99), [#100](‐
3021 https://github.com/PJK/libcbor/issues/100)]
3022 • [Improved CI setup with Travis-native arm64 support](‐
3024 https://github.com/PJK/libcbor/pull/116)
3025 • [Docs migrated to Sphinx 2.4 and Python3](‐
3027 https://github.com/PJK/libcbor/pull/117)
3028 0.5.0 (2017-02-06)
3030 • Remove cmocka from the subtree (always rely on system or user-pro‐
3031 vided version)
3032 • Windows CI
3034 • Only build tests if explicitly enabled (-DWITH_TESTS=ON)
3036 • Fixed static header declarations (by cedric-d)
3038 • Improved documentation (by Michael Richardson)
3040 • Improved examples/readfile.c
3042 • Reworked (re)allocation to handle huge inputs and overflows in size_t
3044 [[Fixes #16]](https://github.com/PJK/libcbor/issues/16)
3045 • Improvements to C++ linkage (corrected cbor_empty_callbacks, fixed
3047 restrict pointers) (by Dennis Bijwaard)
3048 • Fixed Linux installation directory depending on architecture [[Fixes
3050 #34]](https://github.com/PJK/libcbor/issues/34) (by jvymazal)
3051 • Improved 32-bit support [[Fixes #35]](‐
3053 https://github.com/PJK/libcbor/issues/35)
3054 • Fixed MSVC compatibility [[Fixes #31]](‐
3056 https://github.com/PJK/libcbor/issues/31)
3057 • Fixed and improved half-float encoding [[Fixes #5](‐
3059 https://github.com/PJK/libcbor/issues/5), [#11](‐
3060 https://github.com/PJK/libcbor/issues/11)]
3061 0.4.0 (2015-12-25)
3063 Breaks build & header compatibility due to:
3064 • Improved build configuration and feature check macros
3066 • Endianess configuration fixes (by Erwin Kroon and David Grigsby)
3068 • pkg-config compatibility (by Vincent Bernat)
3070 • enable use of versioned SONAME (by Vincent Bernat)
3072 • better fuzzer (wasn't random until now, ooops)
3074 0.3.1 (2015-05-21)
3076 • documentation and comments improvements, mostly for the API reference
3077 0.3.0 (2015-05-21)
3079 • Fixes, polishing, niceties across the code base
3080 • Updated examples
3082 • cbor_copy
3084 • cbor_build_negint8, 16, 32, 64, matching asserts
3086 • cbor_build_stringn
3088 • cbor_build_tag
3090 • cbor_build_float2, ...
3092 0.2.1 (2015-05-17)
3094 • C99 support
3095 0.2.0 (2015-05-17)
3097 • cbor_ctrl_bool -> cbor_ctrl_is_bool
3098 • Added cbor_array_allocated & map equivalent
3100 • Overhauled endianess conversion - ARM now works as expected
3102 • 'sort.c' example added
3104 • Significantly improved and doxyfied documentation
3106 0.1.0 (2015-05-06)
3108 The initial release, yay!
3109 Development
3111 Vision and principles
3112 Consistency and coherence are one of the key characteristics of good
3113 software. While the reality is never black and white, it is important
3114 libcbor contributors are working towards the same high-level goal. This
3115 document attempts to set out the basic principles of libcbor and the
3116 rationale behind them. If you are contributing to libcbor or looking to
3117 evaluate whether libcbor is the right choice for your project, it might
3118 be worthwhile to skim through the section below.
3119 Mission statement
3121 libcbor is the compact, full-featured, and safe CBOR library that works
3122 everywhere.
3123 Goals
3125 RFC-conformance and full feature support
3126 Anything the standard allows, libcbor can do.
3127 Why? Because conformance and interoperability is the point of defining
3129 standards. Clients expect the support to be feature-complete and there
3130 is no significant complexity reduction that can be achieved by slightly
3131 cutting corners, which means that the incremental cost of full RFC sup‐
3132 port is comparatively small over "almost-conformance" seen in many al‐
3133 ternatives.
3134 Safety
3136 Untrusted bytes from the network are the typical input.
3137 Why? Because it is the client expectation. Vast majority of security
3139 vulnerabilities are violations of contracts -- in other words, bugs --
3140 anyway.
3141 Self-containment
3143 libcbor has no runtime dependencies.
3144 Why? Because any constraint imposed on libcbor has to be enforced tran‐
3146 sitively, which is difficult and leads to incompatibilities and distri‐
3147 bution issues, especially in IoT applications.
3148 Portability
3150 If you can compile C for it, libcbor will work there.
3151 Why? Lowest-common-denominator solution for system-level and IoT soft‐
3153 ware was the original niche of libcbor. Users who rely on libcbor ex‐
3154 pect future updates to work on their target platform.
3155 Stable and predictable API
3157 libcbor will not break without a warning.
3158 Why? Industry-standard versioning is a basic requirement for produc‐
3160 tion-quality software. This is especially relevant in IoT environments
3161 where updates may be costly.
3162 Performance
3164 libcbor is fast and resource-efficient by design
3165 Why? Because the main maintainer is an avid hater of slow bloated soft‐
3167 ware. Who wouldn't want more bang per their electricity buck?
3168 Non-goals
3170 • Convenience -- libcbor only provides the minimum surface to make
3171 it usable
3172 • FFI/SWIG/interop support -- libcbor is primarily a C library for C
3174 clients
3175 • One-off usecases support -- although there are primitives to re‐
3177 use, the basic assumption is that most clients want most of CBOR
3178 features
3179 Development dependencies
3181 • CMocka (testing)
3182 • Python and pip (Sphinx platform)
3184 • Doxygen
3186 • Sphinx (documentation)
3188 • There are some Ruby scripts in misc
3190 • Valgrind (memory correctness & profiling)
3192 • GCOV/LCOV (test coverage)
3194 • clang-format
3196 Installing sphinx
3198 pip install sphinx
3199 pip install sphinx_rtd_theme
3200 pip install breathe
3201 pip install https://github.com/lepture/python-livereload/archive/master.zip
3202 pip install sphinx-autobuild
3203 Further instructions on configuring advanced features can be found at
3205 http://read-the-docs.readthedocs.org/en/latest/install.html.
3206 Live preview of docs
3208 cd doc
3209 make livehtml
3210 Set up git hooks
3212 A catch-all git hook that runs clang-format and automatically refreshes
3213 the GH pages contents located in docs can be symlinked:
3214 ln -sf $(pwd)/misc/hooks/pre-commit .git/hooks
3216 Testing and code coverage
3218 Please refer to Tests
3219
3221 Pavel Kalvoda
3222
3224 2023 - 2020, Pavel Kalvoda
32250.10 Jul 20, 2023 LIBCBOR(3)