1LIBCBOR(1)                          libcbor                         LIBCBOR(1)
2
3
4

NAME

6       libcbor - libcbor Documentation
7
8       Documentation for version 0.7.0, updated on Jan 26, 2021.
9

OVERVIEW

11       libcbor  is  a  C  library  for  parsing  and generating CBOR, the gen‐
12       eral-purpose schema-less binary data format.
13
14       Main features
15
16              • Complete RFC conformance [1]
17
18              • Robust C99 implementation
19
20              • Layered architecture offers both control and convenience
21
22              • Flexible memory management
23
24              • No shared global state - threading friendly [2]
25
26              • Proper handling of UTF-8
27
28              • Full support for streams & incremental processing
29
30              • Extensive documentation and test suite
31
32              • No runtime dependencies, small footprint
33
34       [1]  See rfc_conformance
35
36       [2]  With the exception of custom memory allocators (see  api/item_ref‐
37            erence_counting)
38

CONTENTS

40   Getting started
41       Pre-built Linux packages are distributed from the libcbor website.
42
43       OS X users can use Homebrew:
44
45          brew tap pjk/libcbor
46          brew install libcbor
47
48       For other platforms, you will need to compile it from source.
49
50   Building & installing libcbor
51       Prerequisites:
52
53              • C99 compiler
54
55CMake 2.8 or newer (might also be called cmakesetup, cmake-gui
56                or ccmake depending on the installed version and system)
57
58              • C build system CMake can target  (make,  Apple  Xcode,  MinGW,
59                ...)
60
61       NOTE:
62          As of May 2015, not even the 2015 release candidate of Visual Studio
63          supports C99. While CMake will be happy to generate  a  VS  solution
64          that  you  can play with, libcbor currently cannot be compiled using
65          the MSVC toolchain. ICC, GCC under Cygwin, and MinGW's GCC will  all
66          work. The MinGW build process is described below.
67
68       Configuration options
69
70       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
74     ┌─────────────────┬──────────────────┬──────────────────┬──────────────────┐
75     │Option           │ Meaning          │ Default          │ Possible values  │
76     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
77CMAKE_C_COMPILER │ C   compiler  to │ cc               gcc,      clang, │
78     │                 │ use              │                  │ clang-3.5, ...   │
79     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
80CMAKE_IN‐        │ Installation     │ System-dependent │ /usr/local/lib,  │
81STALL_PREFIX     │ prefix           │                  │ ...              │
82     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
83HUGE_FUZZ        │ Fuzz  test  with │ OFF              ON, OFF          
84     │                 │ 8GB of data      │                  │                  │
85     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
86SANE_MALLOC      │ Assume    malloc OFF              ON, OFF          
87     │                 │ will refuse  un‐ │                  │                  │
88     │                 │ reasonable allo‐ │                  │                  │
89     │                 │ cations          │                  │                  │
90     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
91COVERAGE         │ Generate    test │ OFF              ON, OFF          
92     │                 │ coverage instru‐ │                  │                  │
93     │                 │ mentation        │                  │                  │
94     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
95WITH_TESTS       │ Build unit tests │ OFF              ON, OFF          
96     │                 │ (see    develop‐ │                  │                  │
97     │                 │ ment)            │                  │                  │
98     └─────────────────┴──────────────────┴──────────────────┴──────────────────┘
99
100       The following configuration options will also be defined as  macros[#]_
101       in <cbor/common.h> and can therefore be used in client code:
102
103        ┌────────────────────┬──────────────────┬─────────┬─────────────────┐
104        │Option              │ Meaning          │ Default │ Possible values │
105        ├────────────────────┼──────────────────┼─────────┼─────────────────┤
106CBOR_CUSTOM_AL‐     │ Enable    custom │ OFF     ON, OFF         
107LOC                 │ allocator   sup‐ │         │                 │
108        │                    │ port             │         │                 │
109        ├────────────────────┼──────────────────┼─────────┼─────────────────┤
110CBOR_PRETTY_PRINTER │ Include        a │ ON      ON, OFF         
111        │                    │ pretty-printing  │         │                 │
112        │                    │ routine          │         │                 │
113        ├────────────────────┼──────────────────┼─────────┼─────────────────┤
114CBOR_BUFFER_GROWTH  │ Factor  for buf‐ │ 2       │ Decimals > 1    │
115        │                    │ fer   growth   & │         │                 │
116        │                    │ shrinking        │         │                 │
117        └────────────────────┴──────────────────┴─────────┴─────────────────┘
118
119       [1]  ON & OFF will be translated to 1 and 0 using cmakedefine.
120
121            If you want to pass other custom configuration options, please re‐
122            fer to http://www.cmake.org/Wiki/CMake_Useful_Variables.
123
124            Building using make
125
126            CMake will generate a Makefile and other configuration  files  for
127            the build. As a rule of thumb, you should configure the build out‐
128            side of the source tree in order to keep different  configurations
129            isolated. If you are unsure where to execute the build, just use a
130            temporary directory:
131
132          cd $(mktemp -d /tmp/cbor_build.XXXX)
133
134       Now, assuming you are in the directory where you want to build, execute
135       the following to configure the build and run make
136
137          cmake -DCMAKE_BUILD_TYPE=Release path_to_libcbor_dir
138          make cbor cbor_shared
139
140       Both  the  shared  (libcbor.so)  and  the  static (libcbor.a) libraries
141       should now be in the src subdirectory.
142
143       In order to install the libcbor headers and libraries, the usual
144
145          make install
146
147       is what your're looking for. Root permissions are required on most sys‐
148       tems when using the default installation prefix.
149
150       Portability
151
152       libcbor  is  highly  portable  and works on both little- and big-endian
153       systems regardless of the operating system. After building on an exotic
154       platform,  you  might  wish  to  verify  the result by running the test
155       suite. If you encounter any problems, please report them to  the  issue
156       tracker.
157
158       libcbor   is  known  to  successfully  work  on  ARM  Android  devices.
159       Cross-compilation is possible with arm-linux-gnueabi-gcc.
160
161   Linking with libcbor
162       If you include and linker paths include the directories to which  libc‐
163       bor  has  been installed, compiling programs that uses libcbor requires
164       no extra considerations.
165
166       You can verify that everything has been set up properly by  creating  a
167       file with the following contents
168
169          #include <cbor.h>
170          #include <stdio.h>
171
172          int main(int argc, char * argv[])
173          {
174              printf("Hello from libcbor %s\n", CBOR_VERSION);
175          }
176
177       and compiling it
178
179          cc hello_cbor.c -lcbor -o hello_cbor
180
181       libcbor also comes with pkg-config support. If you install libcbor with
182       a custom prefix, you can use pkg-config to resolve the headers and  ob‐
183       jects:
184
185          cc $(pkg-config --cflags libcbor) hello_cbor.c $(pkg-config --libs libcbor) -o hello_cbor
186
187       A note on linkage
188
189       libcbor  is  primarily intended to be linked statically. The shared li‐
190       brary versioning scheme generally follows SemVer, but is irregular  for
191       the 0.X.Y development branch for historical reasons. The following ver‐
192       sion identifiers are used as a part of the SONAME (Linux) or the  dylib
193       "Compatibility version" (OS X):
194
195          • 0.Y  for the 0.Y.Z branch. Patches are backwards compatible, minor
196            releases are generally not and require re-compilation of  any  de‐
197            pendent code.
198
199          • X  for the X.Y.Z stable versions starting 1.X.Y. All minor release
200            of the major version are backwards compatible.
201
202       WARNING:
203          Please note that releases up to and including v0.6.0 may export mis‐
204          leading .so/.dylib version number.
205
206   MinGW build instructions
207       Prerequisites:
208
209              • MinGW
210
211              • CMake GUI
212
213       First  of  all,  create  a folder that will be used for the output. For
214       this demonstration, we will use cbor_out. Start CMake  and  select  the
215       source path and the destination folder.  [image]
216
217       Then  hit  the  'Configure'  button. You will be prompted to select the
218       build system: [image]
219
220       Choose MinGW and confirm.
221
222       NOTE:
223          If you select Visual Studio at this point, a MSVC  project  will  be
224          generated for you. This is useful if you just want to browse through
225          the source code.
226
227       You can then adjust the build options.  The  defaults  will  work  just
228       fine. Hit 'Generate' when you are done.  [image]
229
230       You  can  then  adjust  the  build options. The defaults will work just
231       fine. Hit 'Generate' when you are done.
232
233       Open the shell, navigate to the output directory, and run  mingw32-make
234       cbor cbor_shared.  [image]
235
236       libcbor  will be built and your .dll should be ready at this point [im‐
237       age]
238
239       Feel free to also try building and running some of the  examples,  e.g.
240       mingw32-make sort [image]
241
242   Troubleshooting
243       cbor.h not found: The headers directory is probably not in your include
244       path. First, verify the installation location by checking the installa‐
245       tion log. If you used make, it will look something like
246
247          ...
248          -- Installing: /usr/local/include/cbor
249          -- Installing: /usr/local/include/cbor/callbacks.h
250          -- Installing: /usr/local/include/cbor/encoding.h
251          ...
252
253       Make  sure  that CMAKE_INSTALL_PREFIX (if you provided it) was correct.
254       Including the path path during compilation should suffice, e.g.:
255
256          cc -I/usr/local/include hello_cbor.c -lcbor -o hello_cbor
257
258       cannot find -lcbor during linking: Most likely the same problem as  be‐
259       fore.  Include the installation directory in the linker shared path us‐
260       ing -R, e.g.:
261
262          cc -Wl,-rpath,/usr/local/lib -lcbor -o hello_cbor
263
264       shared library missing during execution: Verify the linkage using  ldd,
265       otool, or similar and adjust the compilation directives accordingly:
266
267          ⇒  ldd hello_cbor
268              linux-vdso.so.1 =>  (0x00007ffe85585000)
269              libcbor.so => /usr/local/lib/libcbor.so (0x00007f9af69da000)
270              libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f9af65eb000)
271              /lib64/ld-linux-x86-64.so.2 (0x00007f9af6be9000)
272
273       compilation  failed:  If your compiler supports C99 yet the compilation
274       has failed, please report the issue to the issue tracker.
275
276   Usage & preliminaries
277   Version information
278       libcbor exports its version using three self-explanatory macros:
279
280CBOR_MAJOR_VERSION
281
282CBOR_MINOR_VERSION
283
284CBOR_PATCH_VERSION
285
286       The CBOR_VERSION is a string concatenating these three identifiers into
287       one (e.g. 0.2.0).
288
289       In  order to simplify version comparisons, the version is also exported
290       as
291
292          #define CBOR_HEX_VERSION ((CBOR_MAJOR_VERSION << 16) | (CBOR_MINOR_VERSION << 8) | CBOR_PATCH_VERSION)
293
294       Since macros are difficult to work with through FFIs, the same informa‐
295       tion is also available through three uint8_t constants, namely
296
297cbor_major_version
298
299cbor_minor_version
300
301cbor_patch_version
302
303   Headers to include
304       The  cbor.h  header  includes  all the symbols. If, for any reason, you
305       don't want to include all the exported symbols, feel free to  use  just
306       some of the cbor/*.h headers:
307
308cbor/arrays.h - api/type_4
309
310cbor/bytestrings.h - api/type_2
311
312cbor/callbacks.h - Callbacks used for streaming/decoding
313
314cbor/common.h - Common utilities - always transitively included
315
316cbor/data.h  -  Data  types  definitions - always transitively in‐
317            cluded
318
319cbor/encoding.h - Streaming encoders for streaming/encoding
320
321cbor/floats_ctrls.h - api/type_7
322
323cbor/ints.h - api/type_0_1
324
325cbor/maps.h - api/type_5
326
327cbor/serialization.h - High level serialization such as cbor_seri‐
328            alize()
329
330cbor/streaming.h - Home of cbor_stream_decode()
331
332cbor/strings.h - api/type_3
333
334cbor/tags.h - api/type_6
335
336   Using libcbor
337       If  you  want  to get more familiar with CBOR, we recommend the cbor.io
338       website. Once you get the grasp of what is it CBOR does,  the  examples
339       (located  in the examples directory) should give you a good feel of the
340       API. The API documentation should then provide with all the information
341       you may need.
342
343       Creating and serializing items
344
345          #include "cbor.h"
346          #include <stdio.h>
347
348          int main(int argc, char * argv[])
349          {
350              /* Preallocate the map structure */
351              cbor_item_t * root = cbor_new_definite_map(2);
352              /* Add the content */
353              cbor_map_add(root, (struct cbor_pair) {
354                  .key = cbor_move(cbor_build_string("Is CBOR awesome?")),
355                  .value = cbor_move(cbor_build_bool(true))
356              });
357              cbor_map_add(root, (struct cbor_pair) {
358                  .key = cbor_move(cbor_build_uint8(42)),
359                  .value = cbor_move(cbor_build_string("Is the answer"))
360              });
361              /* Output: `length` bytes of data in the `buffer` */
362              unsigned char * buffer;
363              size_t buffer_size, length = cbor_serialize_alloc(root, &buffer, &buffer_size);
364
365              fwrite(buffer, 1, length, stdout);
366              free(buffer);
367
368              fflush(stdout);
369              cbor_decref(&root);
370          }
371
372       Reading serialized data
373
374          #include "cbor.h"
375          #include <stdio.h>
376
377          /*
378           * Reads data from a file. Example usage:
379           * $ ./examples/readfile examples/data/nested_array.cbor
380           */
381
382          int main(int argc, char * argv[])
383          {
384              FILE * f = fopen(argv[1], "rb");
385              fseek(f, 0, SEEK_END);
386              size_t length = (size_t)ftell(f);
387              fseek(f, 0, SEEK_SET);
388              unsigned char * buffer = malloc(length);
389              fread(buffer, length, 1, f);
390
391              /* Assuming `buffer` contains `info.st_size` bytes of input data */
392              struct cbor_load_result result;
393              cbor_item_t * item = cbor_load(buffer, length, &result);
394              /* Pretty-print the result */
395              cbor_describe(item, stdout);
396              fflush(stdout);
397              /* Deallocate the result */
398              cbor_decref(&item);
399
400              fclose(f);
401          }
402
403       Using the streaming parser
404
405          #include "cbor.h"
406          #include <stdio.h>
407          #include <string.h>
408
409          /*
410           * Illustrates how one might skim through a map (which is assumed to have
411           * string keys and values only), looking for the value of a specific key
412           *
413           * Use the examples/data/map.cbor input to test this.
414           */
415
416          const char * key = "a secret key";
417          bool key_found = false;
418
419          void find_string(void * _ctx, cbor_data buffer, size_t len)
420          {
421              if (key_found) {
422                  printf("Found the value: %*s\n", (int) len, buffer);
423                  key_found = false;
424              } else if (len == strlen(key)) {
425                  key_found = (memcmp(key, buffer, len) == 0);
426              }
427          }
428
429          int main(int argc, char * argv[])
430          {
431              FILE * f = fopen(argv[1], "rb");
432              fseek(f, 0, SEEK_END);
433              size_t length = (size_t)ftell(f);
434              fseek(f, 0, SEEK_SET);
435              unsigned char * buffer = malloc(length);
436              fread(buffer, length, 1, f);
437
438              struct cbor_callbacks callbacks = cbor_empty_callbacks;
439              struct cbor_decoder_result decode_result;
440              size_t bytes_read = 0;
441              callbacks.string = find_string;
442              while (bytes_read < length) {
443                  decode_result = cbor_stream_decode(buffer + bytes_read,
444                                                     length - bytes_read,
445                                                     &callbacks, NULL);
446                  bytes_read += decode_result.read;
447              }
448
449              fclose(f);
450          }
451
452   API
453       The  data  API is centered around cbor_item_t, a generic handle for any
454       CBOR item. There are functions to
455
456          • create items,
457
458          • set items' data,
459
460          • parse serialized data into items,
461
462          • manage, move, and links item together.
463
464       The single most important thing to keep in mind is: cbor_item_t  is  an
465       opaque  type and should only be manipulated using the appropriate func‐
466       tions! Think of it as an object.
467
468       The libcbor API closely follows the semantics outlined  by  CBOR  stan‐
469       dard.  This  part of the documentation provides a short overview of the
470       CBOR constructs, as well as a general introduction to the libcbor  API.
471       Remaining  reference  can be found in the following files structured by
472       data types.
473
474       The API is designed to allow both very tight control & flexibility  and
475       general  convenience  with  sane defaults. [1] For example, client with
476       very specific requirements (constrained environment, custom application
477       protocol  built  on  top of CBOR, etc.) may choose to take full control
478       (and responsibility) of memory and data structures management by inter‐
479       acting directly with the decoder. Other clients might want to take con‐
480       trol of specific aspects (streamed collections, hash maps storage), but
481       leave  other  responsibilities  to  libcbor. More general clients might
482       prefer to be abstracted away from all aforementioned details  and  only
483       be presented complete data structures.
484
485       libcbor provides
486
487              • stateless encoders and decoders
488
489              • encoding and decoding drivers, routines that coordinate encod‐
490                ing and decoding of complex structures
491
492              • data structures to represent and transform CBOR structures
493
494              • routines for building and manipulating these structures
495
496              • utilities for inspection and debugging
497
498   Types of items
499       Every cbor_item_t has a cbor_type associated with it - these  constants
500       correspond to the types specified by the CBOR standard:
501
502       enum cbor_type
503              Specifies the Major type of cbor_item_t.
504
505              Values:
506
507              enumerator CBOR_TYPE_UINT
508                     0 - positive integers
509
510              enumerator CBOR_TYPE_NEGINT
511                     1 - negative integers
512
513              enumerator CBOR_TYPE_BYTESTRING
514                     2 - byte strings
515
516              enumerator CBOR_TYPE_STRING
517                     3 - strings
518
519              enumerator CBOR_TYPE_ARRAY
520                     4 - arrays
521
522              enumerator CBOR_TYPE_MAP
523                     5 - maps
524
525              enumerator CBOR_TYPE_TAG
526                     6 - tags
527
528              enumerator CBOR_TYPE_FLOAT_CTRL
529                     7 - decimals and special values (true, false, nil, ...)
530
531       To find out the type of an item, one can use
532
533       cbor_type cbor_typeof(const cbor_item_t *item)
534              Get the type of the item.
535
536
537              Return The type
538
539              Parameters
540
541item[borrow]:
542
543
544       Please  note the distinction between functions like cbor_isa_uint() and
545       cbor_is_int(). The following functions work solely with the major  type
546       value.
547
548   Binary queries
549       Alternatively, there are functions to query each particular type.
550
551       WARNING:
552          Passing  an  invalid cbor_item_t reference to any of these functions
553          results in undefined behavior.
554
555       bool cbor_isa_uint(const cbor_item_t *item)
556              Does the item have the appropriate major type?
557
558
559              Return Is the item an CBOR_TYPE_UINT?
560
561              Parameters
562
563item[borrow]: the item
564
565
566       bool cbor_isa_negint(const cbor_item_t *item)
567              Does the item have the appropriate major type?
568
569
570              Return Is the item a CBOR_TYPE_NEGINT?
571
572              Parameters
573
574item[borrow]: the item
575
576
577       bool cbor_isa_bytestring(const cbor_item_t *item)
578              Does the item have the appropriate major type?
579
580
581              Return Is the item a CBOR_TYPE_BYTESTRING?
582
583              Parameters
584
585item[borrow]: the item
586
587
588       bool cbor_isa_string(const cbor_item_t *item)
589              Does the item have the appropriate major type?
590
591
592              Return Is the item a CBOR_TYPE_STRING?
593
594              Parameters
595
596item[borrow]: the item
597
598
599       bool cbor_isa_array(const cbor_item_t *item)
600              Does the item have the appropriate major type?
601
602
603              Return Is the item an CBOR_TYPE_ARRAY?
604
605              Parameters
606
607item[borrow]: the item
608
609
610       bool cbor_isa_map(const cbor_item_t *item)
611              Does the item have the appropriate major type?
612
613
614              Return Is the item a CBOR_TYPE_MAP?
615
616              Parameters
617
618item[borrow]: the item
619
620
621       bool cbor_isa_tag(const cbor_item_t *item)
622              Does the item have the appropriate major type?
623
624
625              Return Is the item a CBOR_TYPE_TAG?
626
627              Parameters
628
629item[borrow]: the item
630
631
632       bool cbor_isa_float_ctrl(const cbor_item_t *item)
633              Does the item have the appropriate major type?
634
635
636              Return Is the item a CBOR_TYPE_FLOAT_CTRL?
637
638              Parameters
639
640item[borrow]: the item
641
642
643   Logical queries
644       These functions provide information about the item  type  from  a  more
645       high-level perspective
646
647       bool cbor_is_int(const cbor_item_t *item)
648              Is the item an integer, either positive or negative?
649
650
651              Return Is the item an integer, either positive or negative?
652
653              Parameters
654
655item[borrow]: the item
656
657
658       bool cbor_is_float(const cbor_item_t *item)
659              Is the item an a floating point number?
660
661
662              Return Is the item a floating point number?
663
664              Parameters
665
666item[borrow]: the item
667
668
669       bool cbor_is_bool(const cbor_item_t *item)
670              Is the item an a boolean?
671
672
673              Return Is the item a boolean?
674
675              Parameters
676
677item[borrow]: the item
678
679
680       bool cbor_is_null(const cbor_item_t *item)
681              Does this item represent null
682
683
684              WARNING:
685                 This  is in no way related to the value of the pointer. Pass‐
686                 ing a
687
688              null pointer will most likely result in a crash.
689
690               .INDENT 7.0
691
692       Return Is the item (CBOR logical) null?
693
694       Parameters
695
696item[borrow]: the item
697
698
699       bool cbor_is_undef(const cbor_item_t *item)
700              Does this item represent undefined
701
702
703              WARNING:
704                 Care must be taken to distinguish nulls and undefined  values
705                 in
706
707              C.
708
709               .INDENT 7.0
710
711       Return Is the item (CBOR logical) undefined?
712
713       Parameters
714
715item[borrow]: the item
716
717
718   Memory management and reference counting
719       Due  to  the  nature of its domain, libcbor will need to work with heap
720       memory. The stateless decoder and encoder don't allocate any memory.
721
722       If you have specific requirements, you should consider rolling your own
723       driver for the stateless API.
724
725   Using custom allocator
726       libcbor  gives you with the ability to provide your own implementations
727       of malloc, realloc, and free. This can be useful if  you  are  using  a
728       custom  allocator throughout your application, or if you want to imple‐
729       ment custom policies (e.g. tighter restrictions on the amount of  allo‐
730       cated memory).
731
732       In  order  to use this feature, libcbor has to be compiled with the ap‐
733       propriate flags. You can verify the configuration using  the  CBOR_CUS‐
734       TOM_ALLOC macro. A simple usage might be as follows:
735
736          #if CBOR_CUSTOM_ALLOC
737                  cbor_set_allocs(malloc, realloc, free);
738          #else
739             #error "libcbor built with support for custom allocation is required"
740          #endif
741
742       void cbor_set_allocs(_cbor_malloc_t custom_malloc, _cbor_realloc_t cus‐
743       tom_realloc, _cbor_free_t custom_free)
744              Sets the memory management routines to use.
745
746              Only available when CBOR_CUSTOM_ALLOC is truthy
747
748
749              WARNING:
750                 This function modifies the global state and should  therefore
751                 be
752
753              used  accordingly.  Changing the memory handlers while allocated
754              items exist will result in a free/malloc mismatch. This function
755              is not thread safe with respect to both itself and all the other
756              libcbor functions that work with the heap.   ..  note::  realloc
757              implementation  must  correctly  support  NULL reallocation (see
758              e.g. http://en.cppreference.com/w/c/memory/realloc)
759
760
761
762
763              Parameters
764
765custom_malloc: malloc implementation
766
767custom_realloc: realloc implementation
768
769custom_free: free implementation
770
771
772   Reference counting
773       As CBOR items may require complex cleanups at the end  of  their  life‐
774       time,  there  is a reference counting mechanism in place. This also en‐
775       ables very simple GC when integrating libcbor into managed environment.
776       Every item starts its life (by either explicit creation, or as a result
777       of parsing) with reference count set to 1. When  the  refcount  reaches
778       zero, it will be destroyed.
779
780       Items  containing nested items will be destroyed recursively - refcount
781       of every nested item will be decreased by one.
782
783       The destruction is synchronous and renders any pointers to  items  with
784       refcount zero invalid immediately after calling the cbor_decref().
785
786       cbor_item_t *cbor_incref(cbor_item_t *item)
787              Increases the reference count by one.
788
789              No dependent items are affected.
790
791
792              Return the input reference
793
794              Parameters
795
796item[incref]: item the item
797
798
799       void cbor_decref(cbor_item_t **item)
800              Decreases  the  reference count by one, deallocating the item if
801              needed.
802
803              In case the item is deallocated, the reference count of any  de‐
804              pendent items is adjusted accordingly in a recursive manner.
805
806
807              Parameters
808
809item[take]: the item. Set to NULL if deallocated
810
811
812       void cbor_intermediate_decref(cbor_item_t *item)
813              Decreases  the  reference count by one, deallocating the item if
814              needed.
815
816              Convenience wrapper for cbor_decref when its set-to-null  behav‐
817              ior is not needed
818
819
820              Parameters
821
822item[take]: the item
823
824
825       size_t cbor_refcount(const cbor_item_t *item)
826              Get the reference count.
827
828
829              WARNING:
830                 This does not account for transitive references.
831
832
833
834
835              Return the reference count
836
837              Parameters
838
839item[borrow]: the item
840
841
842       cbor_item_t *cbor_move(cbor_item_t *item)
843              Provides CPP-like move construct.
844
845              Decreases  the  reference  count by one, but does not deallocate
846              the item even if its refcount reaches zero. This is  useful  for
847              passing intermediate values to functions that increase reference
848              count. Should only be used with functions that incref their  ar‐
849              guments.
850
851
852              WARNING:
853                 If  the item is moved without correctly increasing the refer‐
854                 ence
855
856              count afterwards, the memory will be leaked.
857
858
859
860
861              Return the item with reference count decreased by one
862
863              Parameters
864
865item[take]: the item
866
867
868       cbor_item_t *cbor_copy(cbor_item_t *item)
869              Deep copy of an item.
870
871              All the reference counts in the new structure are set to one.
872
873
874              Return new CBOR deep copy
875
876              Parameters
877
878item[borrow]: item to copy
879
880
881   Decoding
882       The following diagram  illustrates  the  relationship  among  different
883       parts of libcbor from the decoding standpoint.
884
885          ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
886          │                                                                                              │
887          │                                      Client application                                      │
888          │                                                                                              │
889          │                                                 ┌────────────────────────────────────────────┘
890          │                                                 │                     ↕
891          │                                                 │ ┌──────────────────────────────────────────┐
892          │                                                 │ │                                          │
893          │                                                 │ │          Manipulation routines           │
894          │                                                 │ │                                          │
895          │           ┌─────────────────────────────────────┘ └──────────────────────────────────────────┘
896          │           │     ↑    ↑                  ↑                              ↑
897          │           │     │    │    ┌─────────────╫──────────┬───────────────────┴─┐
898          │           │     │   CDS   │             ║          │                     │
899          │           │     │    │   PDS            ║         PDS                   PDS
900          │           │     ↓    ↓    ↓             ↓          ↓                     ↓
901          │           │ ┌─────────────────┐   ┌────────────────────┐   ┌────────────────────────────┐
902          │           │ │                 │   │                    │   │                            │
903          │           │ │  Custom driver  │ ↔ │  Streaming driver  │ ↔ │       Default driver       │ ↔ CD
904          │           │ │                 │   │                    │   │                            │
905          └───────────┘ └─────────────────┘   └────────────────────┘   └────────────────────────────┘
906                ↕                ↕                        ↕                           ↕
907          ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
908          │                                                                                              │
909          │                            Stateless event─driven decoder                                    │
910          │                                                                                              │
911          └──────────────────────────────────────────────────────────────────────────────────────────────┘
912
913                        (PSD = Provided Data Structures, CDS = Custom Data Structures)
914
915       This  section  will  deal  with the API that is labeled as the "Default
916       driver" in the diagram. That is, routines that decode complete  libcbor
917       data items
918
919       cbor_item_t  *cbor_load(cbor_data  source,  size_t  source_size, struct
920       cbor_load_result *result)
921              Loads data item from a buffer.
922
923
924              Return new CBOR item or NULL on failure. In  that  case,  result
925                     contains location and description of the error.
926
927              Parameters
928
929source: The buffer
930
931source_size:
932
933result[out]: Result indicator. CBOR_ERR_NONE on success
934
935
936   Associated data structures
937       enum cbor_error_code
938              Possible decoding errors.
939
940              Values:
941
942              enumerator CBOR_ERR_NONE
943
944              enumerator CBOR_ERR_NOTENOUGHDATA
945
946              enumerator CBOR_ERR_NODATA
947
948              enumerator CBOR_ERR_MALFORMATED
949
950              enumerator CBOR_ERR_MEMERROR
951                     Memory error - item allocation failed.
952
953                     Is it too big for your allocator?
954
955              enumerator CBOR_ERR_SYNTAXERROR
956                     Stack parsing algorithm failed.
957
958       struct cbor_load_result
959              High-level decoding result.
960
961              Public Members
962
963              struct cbor_error error
964                     Error indicator.
965
966              size_t read
967                     Number of bytes read.
968
969       struct cbor_error
970              High-level decoding error.
971
972              Public Members
973
974              size_t position
975                     Aproximate position.
976
977              cbor_error_code code
978                     Description.
979
980   Encoding
981       The  easiest  way to encode data items is using the cbor_serialize() or
982       cbor_serialize_alloc() functions:
983
984       size_t cbor_serialize(const cbor_item_t *item,  cbor_mutable_data  buf‐
985       fer, size_t buffer_size)
986              Serialize the given item.
987
988
989              Return Length of the result. 0 on failure.
990
991              Parameters
992
993item[borrow]: A data item
994
995buffer: Buffer to serialize to
996
997buffer_size: Size of the buffer
998
999
1000       size_t  cbor_serialize_alloc(const cbor_item_t *item, cbor_mutable_data
1001       *buffer, size_t *buffer_size)
1002              Serialize the given item, allocating buffers as needed.
1003
1004
1005              WARNING:
1006                 It is your responsibility to free the buffer using an
1007
1008              appropriate free implementation.
1009
1010
1011
1012
1013              Return Length of the result. 0 on failure, in which case  buffer
1014                     is NULL.
1015
1016              Parameters
1017
1018item[borrow]: A data item
1019
1020buffer[out]: Buffer containing the result
1021
1022buffer_size[out]: Size of the buffer
1023
1024
1025   Type-specific serializers
1026       In case you know the type of the item you want to serialize beforehand,
1027       you can use one of the type-specific serializers.
1028
1029       NOTE:
1030          Unless compiled in debug mode, these do not verify the type. Passing
1031          an incorrect item will result in an undefined behavior.
1032
1033       size_t  cbor_serialize_uint(const  cbor_item_t *item, cbor_mutable_data
1034       buffer, size_t buffer_size)
1035              Serialize an uint.
1036
1037
1038              Return Length of the result. 0 on failure.
1039
1040              Parameters
1041
1042item[borrow]: A uint
1043
1044buffer: Buffer to serialize to
1045
1046buffer_size: Size of the buffer
1047
1048
1049       size_t cbor_serialize_negint(const cbor_item_t *item, cbor_mutable_data
1050       buffer, size_t buffer_size)
1051              Serialize a negint.
1052
1053
1054              Return Length of the result. 0 on failure.
1055
1056              Parameters
1057
1058item[borrow]: A neging
1059
1060buffer: Buffer to serialize to
1061
1062buffer_size: Size of the buffer
1063
1064
1065       size_t  cbor_serialize_bytestring(const  cbor_item_t  *item, cbor_muta‐
1066       ble_data buffer, size_t buffer_size)
1067              Serialize a bytestring.
1068
1069
1070              Return Length of the result. 0 on failure.
1071
1072              Parameters
1073
1074item[borrow]: A bytestring
1075
1076buffer: Buffer to serialize to
1077
1078buffer_size: Size of the buffer
1079
1080
1081       size_t cbor_serialize_string(const cbor_item_t *item, cbor_mutable_data
1082       buffer, size_t buffer_size)
1083              Serialize a string.
1084
1085
1086              Return Length of the result. 0 on failure.
1087
1088              Parameters
1089
1090item[borrow]: A string
1091
1092buffer: Buffer to serialize to
1093
1094buffer_size: Size of the buffer
1095
1096
1097       size_t  cbor_serialize_array(const cbor_item_t *item, cbor_mutable_data
1098       buffer, size_t buffer_size)
1099              Serialize an array.
1100
1101
1102              Return Length of the result. 0 on failure.
1103
1104              Parameters
1105
1106item[borrow]: An array
1107
1108buffer: Buffer to serialize to
1109
1110buffer_size: Size of the buffer
1111
1112
1113       size_t cbor_serialize_map(const  cbor_item_t  *item,  cbor_mutable_data
1114       buffer, size_t buffer_size)
1115              Serialize a map.
1116
1117
1118              Return Length of the result. 0 on failure.
1119
1120              Parameters
1121
1122item[borrow]: A map
1123
1124buffer: Buffer to serialize to
1125
1126buffer_size: Size of the buffer
1127
1128
1129       size_t  cbor_serialize_tag(const  cbor_item_t  *item, cbor_mutable_data
1130       buffer, size_t buffer_size)
1131              Serialize a tag.
1132
1133
1134              Return Length of the result. 0 on failure.
1135
1136              Parameters
1137
1138item[borrow]: A tag
1139
1140buffer: Buffer to serialize to
1141
1142buffer_size: Size of the buffer
1143
1144
1145       size_t cbor_serialize_float_ctrl(const  cbor_item_t  *item,  cbor_muta‐
1146       ble_data buffer, size_t buffer_size)
1147              Serialize a.
1148
1149
1150              Return Length of the result. 0 on failure.
1151
1152              Parameters
1153
1154item[borrow]: A float or ctrl
1155
1156buffer: Buffer to serialize to
1157
1158buffer_size: Size of the buffer
1159
1160
1161   Types 0 & 1 – Positive and negative integers
1162       CBOR has two types of integers – positive (which may be effectively re‐
1163       garded as unsigned), and negative. There are four possible  widths  for
1164       an integer – 1, 2, 4, or 8 bytes. These are represented by
1165
1166       enum cbor_int_width
1167              Possible widths of CBOR_TYPE_UINT items.
1168
1169              Values:
1170
1171              enumerator CBOR_INT_8
1172
1173              enumerator CBOR_INT_16
1174
1175              enumerator CBOR_INT_32
1176
1177              enumerator CBOR_INT_64
1178
1179   Type 0 - positive integers
1180               ┌────────────────────────┬────────────────────────────┐
1181               │Corresponding cbor_type CBOR_TYPE_UINT             
1182               └────────────────────────┴────────────────────────────┘
1183
1184               │Number of allocations   │ One per lifetime           │
1185               ├────────────────────────┼────────────────────────────┤
1186               │Storage requirements    │ sizeof(cbor_item_t)      + 
1187               │                        │ sizeof(uint*_t)            
1188               └────────────────────────┴────────────────────────────┘
1189
1190       Note: once a positive integer has been created,  its  width  cannot  be
1191       changed.
1192
1193   Type 1 - negative integers
1194               ┌────────────────────────┬────────────────────────────┐
1195               │Corresponding cbor_type CBOR_TYPE_NEGINT           
1196               ├────────────────────────┼────────────────────────────┤
1197               │Number of allocations   │ One per lifetime           │
1198               ├────────────────────────┼────────────────────────────┤
1199               │Storage requirements    │ sizeof(cbor_item_t)      + 
1200               │                        │ sizeof(uint*_t)            
1201               └────────────────────────┴────────────────────────────┘
1202
1203       Note: once a positive integer has been created,  its  width  cannot  be
1204       changed.
1205
1206   Type 0 & 1
1207       Due  to their largely similar semantics, the following functions can be
1208       used for both Type 0 and Type 1 items. One  can  convert  between  them
1209       freely using the conversion functions.
1210
1211       Actual Type of the integer can be checked using item types API.
1212
1213       An  integer  item is created with one of the four widths. Because inte‐
1214       gers' storage is bundled together with the handle, the width cannot  be
1215       changed over its lifetime.
1216
1217       WARNING:
1218          Due  to  the  fact that CBOR negative integers represent integers in
1219          the range [-1, -2^N], cbor_set_uint API  is  somewhat  counter-intu‐
1220          itive  as  the  resulting  logical value is 1 less. This behavior is
1221          necessary in order to permit  uniform  manipulation  with  the  full
1222          range of permitted values. For example, the following snippet
1223
1224              cbor_item_t * item = cbor_new_int8();
1225              cbor_mark_negint(item);
1226              cbor_set_uint8(0);
1227
1228          will  produce  an  item with the logical value of -1. There is, how‐
1229          ever, an upside to this as well: There is only one representation of
1230          zero.
1231
1232   Building new items
1233       cbor_item_t *cbor_build_uint8(uint8_t value)
1234              Constructs a new positive integer.
1235
1236
1237              Return new positive integer or NULL on memory allocation failure
1238
1239              Parameters
1240
1241value: the value to use
1242
1243
1244       cbor_item_t *cbor_build_uint16(uint16_t value)
1245              Constructs a new positive integer.
1246
1247
1248              Return new positive integer or NULL on memory allocation failure
1249
1250              Parameters
1251
1252value: the value to use
1253
1254
1255       cbor_item_t *cbor_build_uint32(uint32_t value)
1256              Constructs a new positive integer.
1257
1258
1259              Return new positive integer or NULL on memory allocation failure
1260
1261              Parameters
1262
1263value: the value to use
1264
1265
1266       cbor_item_t *cbor_build_uint64(uint64_t value)
1267              Constructs a new positive integer.
1268
1269
1270              Return new positive integer or NULL on memory allocation failure
1271
1272              Parameters
1273
1274value: the value to use
1275
1276
1277   Retrieving values
1278       uint8_t cbor_get_uint8(const cbor_item_t *item)
1279              Extracts the integer value.
1280
1281
1282              Return the value
1283
1284              Parameters
1285
1286item[borrow]: positive or negative integer
1287
1288
1289       uint16_t cbor_get_uint16(const cbor_item_t *item)
1290              Extracts the integer value.
1291
1292
1293              Return the value
1294
1295              Parameters
1296
1297item[borrow]: positive or negative integer
1298
1299
1300       uint32_t cbor_get_uint32(const cbor_item_t *item)
1301              Extracts the integer value.
1302
1303
1304              Return the value
1305
1306              Parameters
1307
1308item[borrow]: positive or negative integer
1309
1310
1311       uint64_t cbor_get_uint64(const cbor_item_t *item)
1312              Extracts the integer value.
1313
1314
1315              Return the value
1316
1317              Parameters
1318
1319item[borrow]: positive or negative integer
1320
1321
1322   Setting values
1323       void cbor_set_uint8(cbor_item_t *item, uint8_t value)
1324              Assigns the integer value.
1325
1326
1327              Parameters
1328
1329item[borrow]: positive or negative integer item
1330
1331value:  the  value to assign. For negative integer, the
1332                       logical value is -value - 1
1333
1334
1335       void cbor_set_uint16(cbor_item_t *item, uint16_t value)
1336              Assigns the integer value.
1337
1338
1339              Parameters
1340
1341item[borrow]: positive or negative integer item
1342
1343value: the value to assign. For negative  integer,  the
1344                       logical value is -value - 1
1345
1346
1347       void cbor_set_uint32(cbor_item_t *item, uint32_t value)
1348              Assigns the integer value.
1349
1350
1351              Parameters
1352
1353item[borrow]: positive or negative integer item
1354
1355value:  the  value to assign. For negative integer, the
1356                       logical value is -value - 1
1357
1358
1359       void cbor_set_uint64(cbor_item_t *item, uint64_t value)
1360              Assigns the integer value.
1361
1362
1363              Parameters
1364
1365item[borrow]: positive or negative integer item
1366
1367value: the value to assign. For negative  integer,  the
1368                       logical value is -value - 1
1369
1370
1371   Dealing with width
1372       cbor_int_width cbor_int_get_width(const cbor_item_t *item)
1373              Queries the integer width.
1374
1375
1376              Return the width
1377
1378              Parameters
1379
1380item[borrow]: positive or negative integer item
1381
1382
1383   Dealing with signedness
1384       void cbor_mark_uint(cbor_item_t *item)
1385              Marks the integer item as a positive integer.
1386
1387              The data value is not changed
1388
1389
1390              Parameters
1391
1392item[borrow]: positive or negative integer item
1393
1394
1395       void cbor_mark_negint(cbor_item_t *item)
1396              Marks the integer item as a negative integer.
1397
1398              The data value is not changed
1399
1400
1401              Parameters
1402
1403item[borrow]: positive or negative integer item
1404
1405
1406   Creating new items
1407       cbor_item_t *cbor_new_int8()
1408              Allocates new integer with 1B width.
1409
1410              The width cannot be changed once allocated
1411
1412
1413              Return new  positive  integer or NULL on memory allocation fail‐
1414                     ure. The value is not initialized
1415
1416
1417       cbor_item_t *cbor_new_int16()
1418              Allocates new integer with 2B width.
1419
1420              The width cannot be changed once allocated
1421
1422
1423              Return new positive integer or NULL on memory  allocation  fail‐
1424                     ure. The value is not initialized
1425
1426
1427       cbor_item_t *cbor_new_int32()
1428              Allocates new integer with 4B width.
1429
1430              The width cannot be changed once allocated
1431
1432
1433              Return new  positive  integer or NULL on memory allocation fail‐
1434                     ure. The value is not initialized
1435
1436
1437       cbor_item_t *cbor_new_int64()
1438              Allocates new integer with 8B width.
1439
1440              The width cannot be changed once allocated
1441
1442
1443              Return new positive integer or NULL on memory  allocation  fail‐
1444                     ure. The value is not initialized
1445
1446
1447   Type 2 – Byte strings
1448       CBOR  byte  strings  are just (ordered) series of bytes without further
1449       interpretation (unless there is a tag). Byte string's length may or may
1450       not  be  known  during encoding. These two kinds of byte strings can be
1451       distinguished       using       cbor_bytestring_is_definite()       and
1452       cbor_bytestring_is_indefinite() respectively.
1453
1454       In case a byte string is indefinite, it is encoded as a series of defi‐
1455       nite byte strings. These are called "chunks". For example, the  encoded
1456       item
1457
1458          0xf5            Start indefinite byte string
1459              0x41        Byte string (1B long)
1460                  0x00
1461              0x41        Byte string (1B long)
1462                  0xff
1463              0xff        "Break" control token
1464
1465       represents two bytes, 0x00 and 0xff. This on one hand enables streaming
1466       messages even before they are fully generated, but on the other hand it
1467       adds more complexity to the client code.
1468
1469              ┌───────────────────────────┬────────────────────────────┐
1470              │Corresponding cbor_type    CBOR_TYPE_BYTESTRING       
1471              ├───────────────────────────┼────────────────────────────┤
1472              │Number    of   allocations │ One plus any manipulations │
1473              │(definite)                 │ with the data              │
1474              ├───────────────────────────┼────────────────────────────┤
1475              │Number of allocations (in‐ │ One  plus  logarithmically │
1476              │definite)                  │ many  reallocations  rela‐ │
1477              │                           │ tive  to chunk count       │
1478              ├───────────────────────────┼────────────────────────────┤
1479              │Storage requirements (def‐ │ sizeof(cbor_item_t)      + 
1480              │inite)                     │ length(handle)             
1481              ├───────────────────────────┼────────────────────────────┤
1482              │Storage requirements  (in‐ │ sizeof(cbor_item_t) * (1 + 
1483              │definite)                  │ chunk_count) + chunks      
1484              └───────────────────────────┴────────────────────────────┘
1485
1486   Streaming indefinite byte strings
1487       Please refer to /streaming.
1488
1489   Getting metadata
1490       size_t cbor_bytestring_length(const cbor_item_t *item)
1491              Returns the length of the binary data.
1492
1493              For definite byte strings only
1494
1495
1496              Return length of the binary data. Zero if no chunk has been  at‐
1497                     tached yet
1498
1499              Parameters
1500
1501item[borrow]: a definite bytestring
1502
1503
1504       bool cbor_bytestring_is_definite(const cbor_item_t *item)
1505              Is the byte string definite?
1506
1507
1508              Return Is the byte string definite?
1509
1510              Parameters
1511
1512item[borrow]: a byte string
1513
1514
1515       bool cbor_bytestring_is_indefinite(const cbor_item_t *item)
1516              Is the byte string indefinite?
1517
1518
1519              Return Is the byte string indefinite?
1520
1521              Parameters
1522
1523item[borrow]: a byte string
1524
1525
1526       size_t cbor_bytestring_chunk_count(const cbor_item_t *item)
1527              Get the number of chunks this string consist of.
1528
1529
1530              Return The chunk count. 0 for freshly created items.
1531
1532              Parameters
1533
1534item[borrow]: A indefinite bytestring
1535
1536
1537   Reading data
1538       cbor_mutable_data cbor_bytestring_handle(const cbor_item_t *item)
1539              Get the handle to the binary data.
1540
1541              Definite  items  only.  Modifying  the  data is allowed. In that
1542              case, the caller takes responsibility for the  effect  on  items
1543              this item might be a part of
1544
1545
1546              Return The address of the binary data. NULL if no data have been
1547                     assigned yet.
1548
1549              Parameters
1550
1551item[borrow]: A definite byte string
1552
1553
1554       cbor_item_t **cbor_bytestring_chunks_handle(const cbor_item_t *item)
1555              Get the handle to the array of chunks.
1556
1557              Manipulations with the memory block (e.g. sorting  it)  are  al‐
1558              lowed,  but  the  validity  and the number of chunks must be re‐
1559              tained.
1560
1561
1562              Return array of cbor_bytestring_chunk_count definite bytestrings
1563
1564              Parameters
1565
1566item[borrow]: A indefinite byte string
1567
1568
1569   Creating new items
1570       cbor_item_t *cbor_new_definite_bytestring()
1571              Creates a new definite byte string.
1572
1573              The handle is initialized to NULL and length to 0
1574
1575
1576              Return new definite bytestring. NULL on malloc failure.
1577
1578
1579       cbor_item_t *cbor_new_indefinite_bytestring()
1580              Creates a new indefinite byte string.
1581
1582              The chunks array is initialized to NULL and chunkcount to 0
1583
1584
1585              Return new indefinite bytestring. NULL on malloc failure.
1586
1587
1588   Building items
1589       cbor_item_t *cbor_build_bytestring(cbor_data handle, size_t length)
1590              Creates a new byte string and initializes it.
1591
1592              The handle will be copied to a newly allocated block
1593
1594
1595              Return A new byte string with content  handle.  NULL  on  malloc
1596                     failure.
1597
1598              Parameters
1599
1600handle: Block of binary data
1601
1602length: Length of data
1603
1604
1605   Manipulating existing items
1606       void  cbor_bytestring_set_handle(cbor_item_t  *item,  cbor_mutable_data
1607       data, size_t length)
1608              Set the handle to the binary data.
1609
1610
1611              Parameters
1612
1613item[borrow]: A definite byte string
1614
1615data: The memory block. The caller gives up the  owner‐
1616                       ship  of the block. libcbor will deallocate it when ap‐
1617                       propriate using its free function
1618
1619length: Length of the data block
1620
1621
1622       bool cbor_bytestring_add_chunk(cbor_item_t *item, cbor_item_t *chunk)
1623              Appends a chunk to the bytestring.
1624
1625              Indefinite byte strings only.
1626
1627              May realloc the chunk storage.
1628
1629
1630              Return true on success, false on realloc failure. In that  case,
1631                     the  refcount  of  chunk is not increased and the item is
1632                     left intact.
1633
1634              Parameters
1635
1636item[borrow]: An indefinite byte string
1637
1638item[incref]: A definite byte string
1639
1640
1641   Type 3 – UTF-8 strings
1642       CBOR strings work in much the same ways as type_2.
1643
1644              ┌───────────────────────────┬────────────────────────────┐
1645              │Corresponding cbor_type    CBOR_TYPE_STRING           
1646              ├───────────────────────────┼────────────────────────────┤
1647              │Number   of    allocations │ One plus any manipulations │
1648              │(definite)                 │ with the data              │
1649              └───────────────────────────┴────────────────────────────┘
1650
1651
1652
1653              │Number of allocations (in‐ │ One  plus  logarithmically │
1654              │definite)                  │ many  reallocations  rela‐ │
1655              │                           │ tive  to chunk count       │
1656              ├───────────────────────────┼────────────────────────────┤
1657              │Storage requirements (def‐ │ sizeof(cbor_item_t)      + 
1658              │inite)                     │ length(handle)             
1659              ├───────────────────────────┼────────────────────────────┤
1660              │Storage  requirements (in‐ │ sizeof(cbor_item_t) * (1 + 
1661              │definite)                  │ chunk_count) + chunks      
1662              └───────────────────────────┴────────────────────────────┘
1663
1664   Streaming indefinite strings
1665       Please refer to /streaming.
1666
1667   UTF-8 encoding validation
1668       libcbor  considers  UTF-8  encoding  validity  to  be  a  part  of  the
1669       well-formedness notion of CBOR and therefore invalid UTF-8 strings will
1670       be rejected by the parser. Strings created by the user are not checked.
1671
1672   Getting metadata
1673       size_t cbor_string_length(const cbor_item_t *item)
1674              Returns the length of the underlying string.
1675
1676              For definite strings only
1677
1678
1679              Return length  of the string. Zero if no chunk has been attached
1680                     yet
1681
1682              Parameters
1683
1684item[borrow]: a definite string
1685
1686
1687       bool cbor_string_is_definite(const cbor_item_t *item)
1688              Is the string definite?
1689
1690
1691              Return Is the string definite?
1692
1693              Parameters
1694
1695item[borrow]: a string
1696
1697
1698       bool cbor_string_is_indefinite(const cbor_item_t *item)
1699              Is the string indefinite?
1700
1701
1702              Return Is the string indefinite?
1703
1704              Parameters
1705
1706item[borrow]: a string
1707
1708
1709       size_t cbor_string_chunk_count(const cbor_item_t *item)
1710              Get the number of chunks this string consist of.
1711
1712
1713              Return The chunk count. 0 for freshly created items.
1714
1715              Parameters
1716
1717item[borrow]: A indefinite string
1718
1719
1720   Reading data
1721       cbor_mutable_data cbor_string_handle(const cbor_item_t *item)
1722              Get the handle to the underlying string.
1723
1724              Definite items only. Modifying the  data  is  allowed.  In  that
1725              case,  the  caller  takes responsibility for the effect on items
1726              this item might be a part of
1727
1728
1729              Return The address of the underlying string.  NULL  if  no  data
1730                     have been assigned yet.
1731
1732              Parameters
1733
1734item[borrow]: A definite string
1735
1736
1737       cbor_item_t **cbor_string_chunks_handle(const cbor_item_t *item)
1738              Get the handle to the array of chunks.
1739
1740              Manipulations  with  the  memory block (e.g. sorting it) are al‐
1741              lowed, but the validity and the number of  chunks  must  be  re‐
1742              tained.
1743
1744
1745              Return array of cbor_string_chunk_count definite strings
1746
1747              Parameters
1748
1749item[borrow]: A indefinite string
1750
1751
1752   Creating new items
1753       cbor_item_t *cbor_new_definite_string()
1754              Creates a new definite string.
1755
1756              The handle is initialized to NULL and length to 0
1757
1758
1759              Return new definite string. NULL on malloc failure.
1760
1761
1762       cbor_item_t *cbor_new_indefinite_string()
1763              Creates a new indefinite string.
1764
1765              The chunks array is initialized to NULL and chunkcount to 0
1766
1767
1768              Return new indefinite string. NULL on malloc failure.
1769
1770
1771   Building items
1772       cbor_item_t *cbor_build_string(const char *val)
1773              Creates a new string and initializes it.
1774
1775              The val will be copied to a newly allocated block
1776
1777
1778              Return A new string with content handle. NULL on malloc failure.
1779
1780              Parameters
1781
1782val: A null-terminated UTF-8 string
1783
1784
1785   Manipulating existing items
1786       void  cbor_string_set_handle(cbor_item_t *item, cbor_mutable_data data,
1787       size_t length)
1788              Set the handle to the underlying string.
1789
1790
1791              WARNING:
1792                 Using a pointer to a stack allocated constant is a common
1793
1794              mistake. Lifetime of the string will expire when it goes out  of
1795              scope and the CBOR item will be left inconsistent.
1796
1797
1798
1799
1800              Parameters
1801
1802item[borrow]: A definite string
1803
1804data:  The memory block. The caller gives up the owner‐
1805                       ship of the block. libcbor will deallocate it when  ap‐
1806                       propriate using its free function
1807
1808length: Length of the data block
1809
1810
1811       bool cbor_string_add_chunk(cbor_item_t *item, cbor_item_t *chunk)
1812              Appends a chunk to the string.
1813
1814              Indefinite strings only.
1815
1816              May realloc the chunk storage.
1817
1818
1819              Return true  on success. false on realloc failure. In that case,
1820                     the refcount of chunk is not increased and  the  item  is
1821                     left intact.
1822
1823              Parameters
1824
1825item[borrow]: An indefinite string
1826
1827item[incref]: A definite string
1828
1829
1830   Type 4 – Arrays
1831       CBOR  arrays, just like byte strings and strings, can be encoded either
1832       as definite, or as indefinite.
1833
1834              ┌───────────────────────────┬────────────────────────────┐
1835              │Corresponding cbor_type    CBOR_TYPE_ARRAY            
1836              ├───────────────────────────┼────────────────────────────┤
1837              │Number   of    allocations │ Two plus any manipulations │
1838              │(definite)                 │ with the data              │
1839              ├───────────────────────────┼────────────────────────────┤
1840              │Number of allocations (in‐ │ Two  plus  logarithmically │
1841              │definite)                  │ many  reallocations  rela‐ │
1842              │                           │ tive to additions          │
1843              ├───────────────────────────┼────────────────────────────┤
1844              │Storage requirements (def‐ │ (sizeof(cbor_item_t) +  1) 
1845              │inite)                     │ * size                     
1846              ├───────────────────────────┼────────────────────────────┤
1847              │Storage  requirements (in‐ │ <=  sizeof(cbor_item_t)  + 
1848              │definite)                  │ sizeof(cbor_item_t) * size 
1849              │                           │ * BUFFER_GROWTH            
1850              └───────────────────────────┴────────────────────────────┘
1851
1852   Examples
1853          0x9f        Start indefinite array
1854              0x01        Unsigned integer 1
1855              0xff        "Break" control token
1856
1857          0x9f        Start array, 1B length follows
1858          0x20        Unsigned integer 32
1859              ...        32 items follow
1860
1861   Streaming indefinite arrays
1862       Please refer to /streaming.
1863
1864   Getting metadata
1865       size_t cbor_array_size(const cbor_item_t *item)
1866              Get the number of members.
1867
1868
1869              Return The number of members
1870
1871              Parameters
1872
1873item[borrow]: An array
1874
1875
1876       size_t cbor_array_allocated(const cbor_item_t *item)
1877              Get the size of the allocated storage.
1878
1879
1880              Return The size of the allocated storage (number of items)
1881
1882              Parameters
1883
1884item[borrow]: An array
1885
1886
1887       bool cbor_array_is_definite(const cbor_item_t *item)
1888              Is the array definite?
1889
1890
1891              Return Is the array definite?
1892
1893              Parameters
1894
1895item[borrow]: An array
1896
1897
1898       bool cbor_array_is_indefinite(const cbor_item_t *item)
1899              Is the array indefinite?
1900
1901
1902              Return Is the array indefinite?
1903
1904              Parameters
1905
1906item[borrow]: An array
1907
1908
1909   Reading data
1910       cbor_item_t **cbor_array_handle(const cbor_item_t *item)
1911              Get the array contents.
1912
1913              The items may be reordered and modified as  long  as  references
1914              remain consistent.
1915
1916
1917              Return cbor_array_size items
1918
1919              Parameters
1920
1921item[borrow]: An array
1922
1923
1924       cbor_item_t *cbor_array_get(const cbor_item_t *item, size_t index)
1925              Get item by index.
1926
1927
1928              Return incref The item, or NULL in case of boundary violation
1929
1930              Parameters
1931
1932item[borrow]: An array
1933
1934index: The index
1935
1936
1937   Creating new items
1938       cbor_item_t *cbor_new_definite_array(size_t size)
1939              Create new definite array.
1940
1941
1942              Return new array or NULL upon malloc failure
1943
1944              Parameters
1945
1946size: Number of slots to preallocate
1947
1948
1949       cbor_item_t *cbor_new_indefinite_array()
1950              Create new indefinite array.
1951
1952
1953              Return new array or NULL upon malloc failure
1954
1955
1956   Modifying items
1957       bool cbor_array_push(cbor_item_t *array, cbor_item_t *pushee)
1958              Append to the end.
1959
1960              For  indefinite  items, storage may be realloacted. For definite
1961              items, only the preallocated capacity is available.
1962
1963
1964              Return true on success, false on failure
1965
1966              Parameters
1967
1968array[borrow]: An array
1969
1970pushee[incref]: The item to push
1971
1972
1973       bool cbor_array_replace(cbor_item_t *item,  size_t  index,  cbor_item_t
1974       *value)
1975              Replace item at an index.
1976
1977              The item being replace will be cbor_decref 'ed.
1978
1979
1980              Return true on success, false on allocation failure.
1981
1982              Parameters
1983
1984item[borrow]: An array
1985
1986value[incref]: The item to assign
1987
1988index: The index, first item is 0.
1989
1990
1991       bool   cbor_array_set(cbor_item_t   *item,  size_t  index,  cbor_item_t
1992       *value)
1993              Set item by index.
1994
1995              Creating arrays with holes is not possible
1996
1997
1998              Return true on success, false on allocation failure.
1999
2000              Parameters
2001
2002item[borrow]: An array
2003
2004value[incref]: The item to assign
2005
2006index: The index, first item is 0.
2007
2008
2009   Type 5 – Maps
2010       CBOR maps are the plain old associate hash maps  known  from  JSON  and
2011       many  other  formats  and  languages, with one exception: any CBOR data
2012       item can be a key, not just strings. This is somewhat unusual and  you,
2013       as an application developer, should keep that in mind.
2014
2015       Maps  can  be  either  definite  or indefinite, in much the same way as
2016       type_4.
2017
2018              ┌───────────────────────────┬────────────────────────────┐
2019              │Corresponding cbor_type    CBOR_TYPE_MAP              
2020              ├───────────────────────────┼────────────────────────────┤
2021              │Number   of    allocations │ Two plus any manipulations │
2022              │(definite)                 │ with the data              │
2023              ├───────────────────────────┼────────────────────────────┤
2024              │Number of allocations (in‐ │ Two  plus  logarithmically │
2025              │definite)                  │ many  reallocations  rela‐ │
2026              │                           │ tive to additions          │
2027              ├───────────────────────────┼────────────────────────────┤
2028              │Storage requirements (def‐ │ sizeof(cbor_pair) * size + 
2029              │inite)                     │ sizeof(cbor_item_t)        
2030              ├───────────────────────────┼────────────────────────────┤
2031              │Storage  requirements (in‐ │ <=  sizeof(cbor_item_t)  + 
2032              │definite)                  │ sizeof(cbor_pair) * size * 
2033              │                           │ BUFFER_GROWTH              
2034              └───────────────────────────┴────────────────────────────┘
2035
2036   Streaming maps
2037       Please refer to /streaming.
2038
2039   Getting metadata
2040       size_t cbor_map_size(const cbor_item_t *item)
2041              Get the number of pairs.
2042
2043
2044              Return The number of pairs
2045
2046              Parameters
2047
2048item[borrow]: A map
2049
2050
2051       size_t cbor_map_allocated(const cbor_item_t *item)
2052              Get the size of the allocated storage.
2053
2054
2055              Return Allocated storage size (as the number of cbor_pair items)
2056
2057              Parameters
2058
2059item[borrow]: A map
2060
2061
2062       bool cbor_map_is_definite(const cbor_item_t *item)
2063              Is this map definite?
2064
2065
2066              Return Is this map definite?
2067
2068              Parameters
2069
2070item[borrow]: A map
2071
2072
2073       bool cbor_map_is_indefinite(const cbor_item_t *item)
2074              Is this map indefinite?
2075
2076
2077              Return Is this map indefinite?
2078
2079              Parameters
2080
2081item[borrow]: A map
2082
2083
2084   Reading data
2085       struct cbor_pair *cbor_map_handle(const cbor_item_t *item)
2086              Get the pairs storage.
2087
2088
2089              Return Array of cbor_map_size pairs. Manipulation is possible as
2090                     long as references remain valid.
2091
2092              Parameters
2093
2094item[borrow]: A map
2095
2096
2097   Creating new items
2098       cbor_item_t *cbor_new_definite_map(size_t size)
2099              Create a new definite map.
2100
2101
2102              Return new definite map. NULL on malloc failure.
2103
2104              Parameters
2105
2106size: The number of slots to preallocate
2107
2108
2109       cbor_item_t *cbor_new_indefinite_map()
2110              Create a new indefinite map.
2111
2112
2113              Return new definite map. NULL on malloc failure.
2114
2115              Parameters
2116
2117size: The number of slots to preallocate
2118
2119
2120   Modifying items
2121       bool cbor_map_add(cbor_item_t *item, struct cbor_pair pair)
2122              Add a pair to the map.
2123
2124              For  definite  maps, items can only be added to the preallocated
2125              space. For indefinite maps, the  storage  will  be  expanded  as
2126              needed
2127
2128
2129              Return true  on  success, false if either reallocation failed or
2130                     the preallcoated storage is full
2131
2132              Parameters
2133
2134item[borrow]: A map
2135
2136pair[incref]: The key-value pair to add (incref is mem‐
2137                       ber-wise)
2138
2139
2140   Type 6 – Semantic tags
2141       Tag  are  additional  metadata that can be used to extend or specialize
2142       the meaning or interpretation of the other data items.
2143
2144       For example, one might tag an array of numbers to communicate  that  it
2145       should be interpreted as a vector.
2146
2147       Please consult the official IANA repository of CBOR tags before invent‐
2148       ing new ones.
2149
2150               ┌────────────────────────┬────────────────────────────┐
2151               │Corresponding cbor_type CBOR_TYPE_TAG              
2152               └────────────────────────┴────────────────────────────┘
2153
2154
2155
2156
2157
2158               │Number of allocations   │ One plus any manipulations │
2159               │                        │ with  the  data  realloca‐ │
2160               │                        │ tions relative   to  chunk │
2161               │                        │ count                      │
2162               ├────────────────────────┼────────────────────────────┤
2163               │Storage requirements    │ sizeof(cbor_item_t)  + the 
2164               │                        │ tagged item                
2165               └────────────────────────┴────────────────────────────┘
2166
2167       cbor_item_t *cbor_new_tag(uint64_t value)
2168              Create a new tag.
2169
2170
2171              Return new tag. Item reference is NULL. Returns NULL upon memory
2172                     allocation failure
2173
2174              Parameters
2175
2176value: The tag value. Please consult the tag repository
2177
2178
2179       cbor_item_t *cbor_tag_item(const cbor_item_t *item)
2180              Get the tagged item.
2181
2182
2183              Return incref the tagged item
2184
2185              Parameters
2186
2187item[borrow]: A tag
2188
2189
2190       uint64_t cbor_tag_value(const cbor_item_t *item)
2191              Get tag value.
2192
2193
2194              Return The tag value. Please consult the tag repository
2195
2196              Parameters
2197
2198item[borrow]: A tag
2199
2200
2201       void cbor_tag_set_item(cbor_item_t *item, cbor_item_t *tagged_item)
2202              Set the tagged item.
2203
2204
2205              Parameters
2206
2207item[borrow]: A tag
2208
2209tagged_item[incref]: The item to tag
2210
2211
2212   Type 7 – Floats & control tokens
2213       This  type combines two completely unrelated types of items -- floating
2214       point numbers and special values such as true, false, null, etc. We re‐
2215       fer  to  these  special values as 'control values' or 'ctrls' for short
2216       throughout the code.
2217
2218       Just like integers, they have different possible  width  (resulting  in
2219       different value ranges and precisions).
2220
2221       enum cbor_float_width
2222              Possible widths of CBOR_TYPE_FLOAT_CTRL items.
2223
2224              Values:
2225
2226              enumerator CBOR_FLOAT_0
2227                     Internal use - ctrl and special values.
2228
2229              enumerator CBOR_FLOAT_16
2230                     Half float.
2231
2232              enumerator CBOR_FLOAT_32
2233                     Single float.
2234
2235              enumerator CBOR_FLOAT_64
2236                     Double.
2237
2238               ┌────────────────────────┬────────────────────────────┐
2239               │Corresponding cbor_type CBOR_TYPE_FLOAT_CTRL       
2240               ├────────────────────────┼────────────────────────────┤
2241               │Number of allocations   │ One per lifetime           │
2242               └────────────────────────┴────────────────────────────┘
2243
2244               │Storage requirements    │ sizeof(cbor_item_t)      + 
2245               │                        │ 1/4/8                      
2246               └────────────────────────┴────────────────────────────┘
2247
2248   Getting metadata
2249       bool cbor_float_ctrl_is_ctrl(const cbor_item_t *item)
2250              Is this a ctrl value?
2251
2252
2253              Return Is this a ctrl value?
2254
2255              Parameters
2256
2257item[borrow]: A float or ctrl item
2258
2259
2260       cbor_float_width cbor_float_get_width(const cbor_item_t *item)
2261              Get the float width.
2262
2263
2264              Return The width.
2265
2266              Parameters
2267
2268item[borrow]: A float or ctrl item
2269
2270
2271   Reading data
2272       float cbor_float_get_float2(const cbor_item_t *item)
2273              Get a half precision float.
2274
2275              The item must have the corresponding width
2276
2277
2278              Return half precision value
2279
2280              Parameters
2281
2282[borrow]: A half precision float
2283
2284
2285       float cbor_float_get_float4(const cbor_item_t *item)
2286              Get a single precision float.
2287
2288              The item must have the corresponding width
2289
2290
2291              Return single precision value
2292
2293              Parameters
2294
2295[borrow]: A signle precision float
2296
2297
2298       double cbor_float_get_float8(const cbor_item_t *item)
2299              Get a double precision float.
2300
2301              The item must have the corresponding width
2302
2303
2304              Return double precision value
2305
2306              Parameters
2307
2308[borrow]: A double precision float
2309
2310
2311       double cbor_float_get_float(const cbor_item_t *item)
2312              Get the float value represented as double.
2313
2314              Can be used regardless of the width.
2315
2316
2317              Return double precision value
2318
2319              Parameters
2320
2321[borrow]: Any float
2322
2323
2324       uint8_t cbor_ctrl_value(const cbor_item_t *item)
2325              Reads the control value.
2326
2327
2328              Return the simple value
2329
2330              Parameters
2331
2332item[borrow]: A ctrl item
2333
2334
2335       bool cbor_get_bool(const cbor_item_t *item)
2336              Get value from a boolean ctrl item.
2337
2338
2339              Return boolean value
2340
2341              Parameters
2342
2343item[borrow]: A ctrl item
2344
2345
2346   Creating new items
2347       cbor_item_t *cbor_new_ctrl()
2348              Constructs a new ctrl item.
2349
2350              The width cannot be changed once the item is created
2351
2352
2353              Return new 1B ctrl or NULL upon memory allocation failure
2354
2355
2356       cbor_item_t *cbor_new_float2()
2357              Constructs a new float item.
2358
2359              The width cannot be changed once the item is created
2360
2361
2362              Return new 2B float or NULL upon memory allocation failure
2363
2364
2365       cbor_item_t *cbor_new_float4()
2366              Constructs a new float item.
2367
2368              The width cannot be changed once the item is created
2369
2370
2371              Return new 4B float or NULL upon memory allocation failure
2372
2373
2374       cbor_item_t *cbor_new_float8()
2375              Constructs a new float item.
2376
2377              The width cannot be changed once the item is created
2378
2379
2380              Return new 8B float or NULL upon memory allocation failure
2381
2382
2383       cbor_item_t *cbor_new_null()
2384              Constructs new null ctrl item.
2385
2386
2387              Return new null ctrl item or NULL upon memory allocation failure
2388
2389
2390       cbor_item_t *cbor_new_undef()
2391              Constructs new undef ctrl item.
2392
2393
2394              Return new undef ctrl item or NULL upon memory allocation  fail‐
2395                     ure
2396
2397
2398   Building items
2399       cbor_item_t *cbor_build_bool(bool value)
2400              Constructs new boolean ctrl item.
2401
2402
2403              Return new boolen ctrl item or NULL upon memory allocation fail‐
2404                     ure
2405
2406              Parameters
2407
2408value: The value to use
2409
2410
2411       cbor_item_t *cbor_build_ctrl(uint8_t value)
2412              Constructs a ctrl item.
2413
2414
2415              Return new ctrl item or NULL upon memory allocation failure
2416
2417              Parameters
2418
2419value: the value to use
2420
2421
2422       cbor_item_t *cbor_build_float2(float value)
2423              Constructs a new float.
2424
2425
2426              Return new float
2427
2428              Parameters
2429
2430value: the value to use
2431
2432
2433       cbor_item_t *cbor_build_float4(float value)
2434              Constructs a new float.
2435
2436
2437              Return new float or NULL upon memory allocation failure
2438
2439              Parameters
2440
2441value: the value to use
2442
2443
2444       cbor_item_t *cbor_build_float8(double value)
2445              Constructs a new float.
2446
2447
2448              Return new float or NULL upon memory allocation failure
2449
2450              Parameters
2451
2452value: the value to use
2453
2454
2455   Manipulating existing items
2456       void cbor_set_ctrl(cbor_item_t *item, uint8_t value)
2457              Assign a control value.
2458
2459
2460              WARNING:
2461                 It is possible to produce an invalid CBOR value by  assigning
2462                 a
2463
2464              invalid  value using this mechanism. Please consult the standard
2465              before use.
2466
2467
2468
2469
2470              Parameters
2471
2472item[borrow]: A ctrl item
2473
2474value: The simple value to assign. Please  consult  the
2475                       standard for allowed values
2476
2477
2478       void cbor_set_bool(cbor_item_t *item, bool value)
2479              Assign a boolean value to a boolean ctrl item.
2480
2481
2482              Parameters
2483
2484item[borrow]: A ctrl item
2485
2486value: The simple value to assign.
2487
2488
2489       void cbor_set_float2(cbor_item_t *item, float value)
2490              Assigns a float value.
2491
2492
2493              Parameters
2494
2495item[borrow]: A half precision float
2496
2497value: The value to assign
2498
2499
2500       void cbor_set_float4(cbor_item_t *item, float value)
2501              Assigns a float value.
2502
2503
2504              Parameters
2505
2506item[borrow]: A single precision float
2507
2508value: The value to assign
2509
2510
2511       void cbor_set_float8(cbor_item_t *item, double value)
2512              Assigns a float value.
2513
2514
2515              Parameters
2516
2517item[borrow]: A double precision float
2518
2519value: The value to assign
2520
2521
2522   Half floats
2523       CBOR  supports  two  bytes wide ("half-precision") floats which are not
2524       supported by the  C  language.  libcbor  represents  them  using  float
2525       <https://en.cppreference.com/w/c/language/type>  values  throughout the
2526       API, which has important implications when manipulating these values.
2527
2528       In particular, if a user uses  some  of  the  manipulation  APIs  (e.g.
2529       cbor_set_float2(), cbor_new_float2()) to introduce a value that doesn't
2530       have an exect half-float representation,  the  encoding  semantics  are
2531       given by cbor_encode_half() as follows:
2532
2533       size_t cbor_encode_half(float value, unsigned char *buffer, size_t buf‐
2534       fer_size)
2535              Encodes a half-precision float.
2536
2537              Since there is no native representation or  semantics  for  half
2538              floats in the language, we use single-precision floats, as every
2539              value that can be expressed as a  half-float  can  also  be  ex‐
2540              pressed as a float.
2541
2542              This  however  means that not all floats passed to this function
2543              can be unambiguously encoded. The behavior is as follows:.INDENT
2544              7.0
2545
2546       • Infinity, NaN are preserved
2547
2548       • Zero is preserved
2549
2550       • Denormalized  numbers keep their sign bit and 10 most significant bit
2551         of the significand
2552
2553       • All other numbers.INDENT 2.0
2554
2555       • If the logical value of the exponent is < -24, the output is zero
2556
2557       • If the logical value of the exponent is between -23 and -14, the out‐
2558         put is cut off to represent the 'magnitude' of the input, by which we
2559         mean (-1)^{signbit} x 1.0e{exponent}. The value in the significand is
2560         lost.
2561
2562       • In  all other cases, the sign bit, the exponent, and 10 most signifi‐
2563         cant bits of the significand are kept
2564
2565
2566
2567
2568              Return number of bytes written
2569
2570              Parameters
2571
2572value:
2573
2574buffer: Target buffer
2575
2576buffer_size: Available space in the buffer
2577
2578
2579       [1]  http://softwareengineering.vazexqi.com/files/pattern.html
2580
2581   Streaming & indefinite items
2582       CBOR strings, byte strings, arrays, and maps can be encoded as  indefi‐
2583       nite,  meaning their length or size is not specified. Instead, they are
2584       divided into chunks (strings, byte strings), or  explicitly  terminated
2585       (arrays, maps).
2586
2587       This is one of the most important (and due to poor implementations, un‐
2588       derutilized) features of CBOR. It enables low-overhead  streaming  just
2589       about  anywhere  without dealing with channels or pub/sub mechanism. It
2590       is, however, important to recognize that CBOR streaming is not  a  sub‐
2591       stitute for  Websockets [1] and similar technologies.
2592
2593       [1]  RFC 6455
2594
2595   Decoding
2596       Another way to decode data using libcbor is to specify a callbacks that
2597       will be invoked when upon finding certain items in the input. This ser‐
2598       vice is provided by
2599
2600       struct  cbor_decoder_result cbor_stream_decode(cbor_data buffer, size_t
2601       buffer_size, const struct cbor_callbacks *callbacks, void *context)
2602              Stateless decoder.
2603
2604              Will try parsing the buffer  and  will  invoke  the  appropriate
2605              callback on success. Decodes one item at a time. No memory allo‐
2606              cations occur.
2607
2608
2609              Parameters
2610
2611buffer: Input buffer
2612
2613buffer_size: Length of the buffer
2614
2615callbacks: The callback bundle
2616
2617context: An arbitrary pointer to allow for  maintaining
2618                       context.
2619
2620
2621       To  get  started, you might want to have a look at the simple streaming
2622       example:
2623
2624          #include "cbor.h"
2625          #include <stdio.h>
2626          #include <string.h>
2627
2628          /*
2629           * Illustrates how one might skim through a map (which is assumed to have
2630           * string keys and values only), looking for the value of a specific key
2631           *
2632           * Use the examples/data/map.cbor input to test this.
2633           */
2634
2635          const char * key = "a secret key";
2636          bool key_found = false;
2637
2638          void find_string(void * _ctx, cbor_data buffer, size_t len)
2639          {
2640              if (key_found) {
2641                  printf("Found the value: %*s\n", (int) len, buffer);
2642                  key_found = false;
2643              } else if (len == strlen(key)) {
2644                  key_found = (memcmp(key, buffer, len) == 0);
2645              }
2646          }
2647
2648          int main(int argc, char * argv[])
2649          {
2650              FILE * f = fopen(argv[1], "rb");
2651              fseek(f, 0, SEEK_END);
2652              size_t length = (size_t)ftell(f);
2653              fseek(f, 0, SEEK_SET);
2654              unsigned char * buffer = malloc(length);
2655              fread(buffer, length, 1, f);
2656
2657              struct cbor_callbacks callbacks = cbor_empty_callbacks;
2658              struct cbor_decoder_result decode_result;
2659              size_t bytes_read = 0;
2660              callbacks.string = find_string;
2661              while (bytes_read < length) {
2662                  decode_result = cbor_stream_decode(buffer + bytes_read,
2663                                                     length - bytes_read,
2664                                                     &callbacks, NULL);
2665                  bytes_read += decode_result.read;
2666              }
2667
2668              free(buffer);
2669              fclose(f);
2670          }
2671
2672       The callbacks are defined by
2673
2674       struct cbor_callbacks
2675              Callback bundle  passed to the decoder.
2676
2677              Public Members
2678
2679              cbor_int8_callback uint8
2680                     Unsigned int.
2681
2682              cbor_int16_callback uint16
2683                     Unsigned int.
2684
2685              cbor_int32_callback uint32
2686                     Unsigned int.
2687
2688              cbor_int64_callback uint64
2689                     Unsigned int.
2690
2691              cbor_int64_callback negint64
2692                     Negative int.
2693
2694              cbor_int32_callback negint32
2695                     Negative int.
2696
2697              cbor_int16_callback negint16
2698                     Negative int.
2699
2700              cbor_int8_callback negint8
2701                     Negative int.
2702
2703              cbor_simple_callback byte_string_start
2704                     Definite byte string.
2705
2706              cbor_string_callback byte_string
2707                     Indefinite byte string start.
2708
2709              cbor_string_callback string
2710                     Definite string.
2711
2712              cbor_simple_callback string_start
2713                     Indefinite string start.
2714
2715              cbor_simple_callback indef_array_start
2716                     Definite array.
2717
2718              cbor_collection_callback array_start
2719                     Indefinite array.
2720
2721              cbor_simple_callback indef_map_start
2722                     Definite map.
2723
2724              cbor_collection_callback map_start
2725                     Indefinite map.
2726
2727              cbor_int64_callback tag
2728                     Tags.
2729
2730              cbor_float_callback float2
2731                     Half float.
2732
2733              cbor_float_callback float4
2734                     Single float.
2735
2736              cbor_double_callback float8
2737                     Double float.
2738
2739              cbor_simple_callback undefined
2740                     Undef.
2741
2742              cbor_simple_callback null
2743                     Null.
2744
2745              cbor_bool_callback boolean
2746                     Bool.
2747
2748              cbor_simple_callback indef_break
2749                     Indefinite item break.
2750
2751       When building custom sets of callbacks, feel free to start from
2752
2753       const struct cbor_callbacks cbor_empty_callbacks
2754              Dummy callback bundle - does nothing.
2755
2756   Related structures
2757       enum cbor_decoder_status
2758              Streaming decoder result - status.
2759
2760              Values:
2761
2762              enumerator CBOR_DECODER_FINISHED
2763                     OK, finished.
2764
2765              enumerator CBOR_DECODER_NEDATA
2766                     Not enough data - mismatch with MTB.
2767
2768              enumerator CBOR_DECODER_EBUFFER
2769                     Buffer manipulation problem.
2770
2771              enumerator CBOR_DECODER_ERROR
2772                     Malformed or reserved MTB/value.
2773
2774       struct cbor_decoder_result
2775              Streaming decoder result.
2776
2777              Public Members
2778
2779              size_t read
2780                     Bytes read.
2781
2782              enum cbor_decoder_status status
2783                     The result.
2784
2785              size_t required
2786                     When status == CBOR_DECODER_NEDATA, the minimum number of
2787                     bytes required to continue parsing.
2788
2789   Callback types definition
2790       typedef void (*cbor_int8_callback)(void*, uint8_t)
2791              Callback prototype.
2792
2793       typedef void (*cbor_int16_callback)(void*, uint16_t)
2794              Callback prototype.
2795
2796       typedef void (*cbor_int32_callback)(void*, uint32_t)
2797              Callback prototype.
2798
2799       typedef void (*cbor_int64_callback)(void*, uint64_t)
2800              Callback prototype.
2801
2802       typedef void (*cbor_simple_callback)(void*)
2803              Callback prototype.
2804
2805       typedef void (*cbor_string_callback)(void*, cbor_data, size_t)
2806              Callback prototype.
2807
2808       typedef void (*cbor_collection_callback)(void*, size_t)
2809              Callback prototype.
2810
2811       typedef void (*cbor_float_callback)(void*, float)
2812              Callback prototype.
2813
2814       typedef void (*cbor_double_callback)(void*, double)
2815              Callback prototype.
2816
2817       typedef void (*cbor_bool_callback)(void*, bool)
2818              Callback prototype.
2819
2820   Encoding
2821       TODO
2822
2823   Tests
2824   Unit tests
2825       There  is  a comprehensive test suite employing CMocka. You can run all
2826       of them using ctest in the build directory. Individual tests are  them‐
2827       selves  runnable.  Please refer to CTest documentation for detailed in‐
2828       formation on how to specify particular subset of tests.
2829
2830   Testing for memory leaks
2831       Every release is tested for memory correctness. You can run these tests
2832       by passing the -T memcheck flag to ctest. [1]
2833
2834       [1]  Project  should be configured with -DCMAKE_BUILD_TYPE=Debug to ob‐
2835            tain meaningful description of location of  the  leak.  You  might
2836            also need --dsymutil=yes on OS X.
2837
2838   Code coverage
2839       Every  release  is inspected using GCOV/LCOV. Platform-independent code
2840       should be fully covered by the test suite. Simply run
2841
2842          make coverage
2843
2844       or alternatively run lcov by hand using
2845
2846          lcov --capture --directory . --output-file coverage.info
2847          genhtml coverage.info --output-directory out
2848
2849   Fuzz testing
2850       Every release is tested using a fuzz test. In this test, a huge  buffer
2851       filled  with  random  data is passed to the decoder. We require that it
2852       either succeeds or fail with a sensible error, without leaking any mem‐
2853       ory.  This is intended to simulate real-world situations where data re‐
2854       ceived from the network are CBOR-decoded before any further processing.
2855
2856   RFC conformance
2857       libcbor is, generally speaking, very  faithful  implementation  of  RFC
2858       7049.  There  are,  however, some limitations imposed by technical con‐
2859       straints.
2860
2861   Bytestring length
2862       There is no explicit limitation of indefinite length byte strings.  [1]
2863       libcbor  will not handle byte strings with more chunks than the maximum
2864       value of size_t. On any sane platform, such string would not fit in the
2865       memory  anyway.  It  is,  however, possible to process arbitrarily long
2866       strings and byte strings using the streaming decoder.
2867
2868       [1]  http://tools.ietf.org/html/rfc7049#section-2.2.2
2869
2870   Half-precision IEEE 754 floats
2871       As of C99 and even C11, there is no standard implementation for 2 bytes
2872       floats.   libcbor   packs   them   as   a  float  <https://en.cpprefer
2873       ence.com/w/c/language/type>. When encoding, libcbor selects the  appro‐
2874       priate wire representation based on metadata and the actual value. This
2875       applies both to canonical and normal mode.
2876
2877       For more information on half-float serialization, please refer  to  the
2878       section on api_type_7_hard_floats.
2879
2880   Internal mechanics
2881       Internal workings of libcbor are mostly derived from the specification.
2882       The purpose of this document is to describe technical choices made dur‐
2883       ing design & implementation and to explicate the reasoning behind those
2884       choices.
2885
2886   Terminology
2887     ┌────┬─────────────────────┬────────────────────────────────────────────────┐
2888     │MTB │ Major Type Byte     │ http://tools.ietf.org/html/rfc7049#section-2.1
2889     ├────┼─────────────────────┼────────────────────────────────────────────────┤
2890     │DST │ Dynamically   Sized │ Type whose storage requirements cannot be  de‐ │
2891     │    │ Type                │ termined                                       │
2892     │    │                     │                                                │
2893     │    │                     │ during  compilation  (originated  in  the Rust
2894     │    │                     │ community)                                     │
2895     └────┴─────────────────────┴────────────────────────────────────────────────┘
2896
2897   Conventions
2898       API symbols start with cbor_ or CBOR_  prefix,  internal  symbols  have
2899       _cbor_ or _CBOR_ prefix.
2900
2901   Inspiration & related projects
2902       Most  of the API is largely modelled after existing JSON libraries, in‐
2903       cluding
2904
2905Jansson
2906
2907json-c
2908
2909          • Gnome's JsonGlib
2910
2911       and also borrowing from
2912
2913msgpack-c
2914
2915Google Protocol Buffers.
2916
2917   General notes on the API design
2918       The API design has two main driving priciples:
2919
2920          1. Let the client manage the memory as much as possible
2921
2922          2. Behave exactly as specified by the standard
2923
2924       Combining these two principles in practice turns out to be quite diffi‐
2925       cult.  Indefinite-length  strings,  arrays,  and maps require client to
2926       handle every fixed-size chunk explicitly in order to
2927
2928          • ensure the client never runs out of memory due to libcbor
2929
2930          • use realloc() sparsely and predictably [1]
2931
2932                • provide strong guarantees about its usage  (to  prevent  la‐
2933                  tency spikes)
2934
2935                • provide APIs to avoid realloc() altogether
2936
2937          • allow  proper  handling  of  (streamed) data bigger than available
2938            memory
2939
2940          [1]  Reasonable handling of DSTs requires reallocation if the API is
2941               to remain sane.
2942
2943   Coding style
2944       This code loosely follows the Linux kernel coding style. Tabs are tabs,
2945       and they are 4 characters wide.
2946
2947   Memory layout
2948       CBOR is very dynamic in the sense that it contains many  data  elements
2949       of  variable length, sometimes even indefinite length. This section de‐
2950       scribes internal representation of all CBOR data types.
2951
2952       Generally speaking, data items consist of three parts:
2953
2954          • a generic handle,
2955
2956          • the associated metadata,
2957
2958          • and the actual data
2959
2960       type cbor_item_t
2961              Represents the item. Used as an opaque type
2962
2963              cbor_type type
2964                     Type discriminator
2965
2966              size_t refcount
2967                     Reference counter. Used by cbor_decref(), cbor_incref()
2968
2969              union cbor_item_metadata metadata
2970                     Union discriminated by type. Contains type-specific meta‐
2971                     data
2972
2973              unsigned char *data
2974                     Contains  pointer  to  the actual data. Small, fixed size
2975                     items (api/type_0_1, api/type_6,  api/type_7)  are  allo‐
2976                     cated as a single memory block.
2977
2978                     Consider the following snippet
2979
2980                        cbor_item_t * item = cbor_new_int8();
2981
2982                     then the memory is laid out as follows
2983
2984                        +-----------+---------------+---------------+-----------------------------------++-----------+
2985                        |           |               |               |                                   ||           |
2986                        |   type    |   refcount    |   metadata    |              data                 ||  uint8_t  |
2987                        |           |               |               |   (= item + sizeof(cbor_item_t))  ||           |
2988                        +-----------+---------------+---------------+-----------------------------------++-----------+
2989                        ^                                                                                ^
2990                        |                                                                                |
2991                        +--- item                                                                        +--- item->data
2992
2993                     Dynamically    sized   types   (api/type_2,   api/type_3,
2994                     api/type_4, api/type_5) may store handle and data in sep‐
2995                     arate  locations.  This enables creating large items (e.g
2996                     byte strings) without realloc() or copying  large  blocks
2997                     of memory. One simply attaches the correct pointer to the
2998                     handle.
2999
3000       type cbor_item_metadata
3001              Union type of the following members, based on the item type:
3002
3003              struct _cbor_int_metadata int_metadata
3004                     Used both by both api/type_0_1
3005
3006              struct _cbor_bytestring_metadata bytestring_metadata
3007
3008              struct _cbor_string_metadata string_metadata
3009
3010              struct _cbor_array_metadata array_metadata
3011
3012              struct _cbor_map_metadata map_metadata
3013
3014              struct _cbor_tag_metadata tag_metadata
3015
3016              struct _cbor_float_ctrl_metadata float_ctrl_metadata
3017
3018   Decoding
3019       As outlined in api, there decoding is based on  the  streaming  decoder
3020       Essentially, the decoder is a custom set of callbacks for the streaming
3021       decoder.
3022
3023   Changelog
3024   Next
3025   0.7.0 (2020-04-25)
3026
3027
3028         Fix   bad   encoding   of    NaN    half-floats    [[Fixes    #53]](‐
3029         https://github.com/PJK/libcbor/issues/53)        (discovered       by
3030         [BSipos-RKF](https://github.com/BSipos-RKF))
3031
3032Warning: Previous versions encoded NaNs as 0xf9e700  instead
3033                  of  0xf97e00;  if you rely on the broken behavior, this will
3034                  be a breaking change
3035
3036       • Fix potentially bad encoding of negative half-float with  exponent  <
3037         -14  [[Fixes  #112]](https://github.com/PJK/libcbor/issues/112) (dis‐
3038         covered by [yami36](https://github.com/yami36))
3039
3040
3041
3042         BREAKING:     Improved     bool     support      [[Fixes      #63]](‐
3043         https://github.com/PJK/libcbor/issues/63)
3044
3045                • Rename cbor_ctrl_is_bool to cbor_get_bool and fix the behav‐
3046                  ior
3047
3048                • Add cbor_set_bool
3049
3050       • Fix memory_allocation_test breaking the build without CBOR_CUSTOM_AL‐
3051         LOC   [[Fixes  #128]](https://github.com/PJK/libcbor/issues/128)  (by
3052         [panlinux](https://github.com/panlinux))
3053
3054       • [Fix  a  potential  build  issue  where   cJSON   includes   may   be
3055         misconfigured](https://github.com/PJK/libcbor/pull/132)
3056
3057
3058
3059         Breaking:  [Add  a limit on the size of the decoding context stack](‐
3060         https://github.com/PJK/libcbor/pull/138)     (by      [James-ZHANG](‐
3061         https://github.com/James-ZHANG))
3062
3063                • If  your  usecase requires parsing very deeply nested struc‐
3064                  tures, you might need to increase the default 2k  limit  via
3065                  CBOR_MAX_STACK_SIZE
3066
3067
3068
3069         Enable       LTO/IPO       based       on       [CheckIPOSupported](‐
3070         https://cmake.org/cmake/help/latest/module/CheckIPOSup
3071         ported.html#module:CheckIPOSupported)                      [[#143]](‐
3072         https://github.com/PJK/libcbor/pull/143)      (by      [xanderlent](‐
3073         https://github.com/xanderlent))
3074
3075                • If you rely on LTO being enabled and use CMake version older
3076                  than 3.9, you will need to re-enable it manually or  upgrade
3077                  your CMake
3078
3079   0.6.1 (2020-03-26)
3080
3081
3082         [Fix       bad       shared       library      version      number](‐
3083         https://github.com/PJK/libcbor/pull/131)
3084
3085Warning: Shared library built from the 0.6.0 release is  er‐
3086                  roneously  marked  as version "0.6.0", which makes it incom‐
3087                  patible with future releases including the v0.6.X line  even
3088                  though  they  may  be  compatible API/ABI-wise. Refer to the
3089                  documentation for the new SO versioning scheme.
3090
3091   0.6.0 (2020-03-15)
3092
3093
3094         Correctly      set      .so       version       [[Fixes       #52]](‐
3095         https://github.com/PJK/libcbor/issues/52).
3096
3097Warning:  All previous releases will be identified as 0.0 by
3098                  the linker.
3099
3100       • Fix  &  prevent  heap  overflow  error  in  example  code   [[#74]](‐
3101         https://github.com/PJK/libcbor/pull/74)                     [[#76]](‐
3102         https://github.com/PJK/libcbor/pull/76) (by @nevun)
3103
3104       • Correctly  set  OSX   dynamic   library   version   [[Fixes   #75]](‐
3105         https://github.com/PJK/libcbor/issues/75)
3106
3107       • [Fix   misplaced   0xFF   bytes   in  maps  possibly  causing  memory
3108         corruption](https://github.com/PJK/libcbor/pull/82)
3109
3110       • BREAKING: Fix handling & cleanup of failed memory allocation in  con‐
3111         structor    and    builder    helper    functions   [[Fixes   #84]](‐
3112         https://github.com/PJK/libcbor/issues/84)  -   All   cbor_new_*   and
3113         cbor_build_*  functions  will  now explicitly return NULL when memory
3114         allocation fails - It is up to the client to handle such cases
3115
3116       • Globally      enforced      code      style      [[Fixes      #83]](‐
3117         https://github.com/PJK/libcbor/issues/83)
3118
3119       • Fix    issue    possible    memory   corruption   bug   on   repeated
3120         cbor_(byte)string_add_chunk calls with intermittently failing realloc
3121         calls
3122
3123       • Fix  possibly  misaligned  reads  and writes when endian.h is uses or
3124         when   running   on   a    big-endian    machine    [[Fixes    #99](‐
3125         https://github.com/PJK/libcbor/issues/99),                   [#100](‐
3126         https://github.com/PJK/libcbor/issues/100)]
3127
3128       • [Improved   CI   setup   with    Travis-native    arm64    support](‐
3129         https://github.com/PJK/libcbor/pull/116)
3130
3131       • [Docs      migrated      to     Sphinx     2.4     and     Python3](‐
3132         https://github.com/PJK/libcbor/pull/117)
3133
3134   0.5.0 (2017-02-06)
3135       • Remove cmocka from the subtree (always rely on  system  or  user-pro‐
3136         vided version)
3137
3138       • Windows CI
3139
3140       • Only build tests if explicitly enabled (-DWITH_TESTS=ON)
3141
3142       • Fixed static header declarations (by cedric-d)
3143
3144       • Improved documentation (by Michael Richardson)
3145
3146       • Improved examples/readfile.c
3147
3148       • Reworked (re)allocation to handle huge inputs and overflows in size_t
3149         [[Fixes #16]](https://github.com/PJK/libcbor/issues/16)
3150
3151       • Improvements to C++ linkage  (corrected  cbor_empty_callbacks,  fixed
3152         restrict pointers) (by Dennis Bijwaard)
3153
3154       • Fixed  Linux installation directory depending on architecture [[Fixes
3155         #34]](https://github.com/PJK/libcbor/issues/34) (by jvymazal)
3156
3157       • Improved        32-bit        support         [[Fixes         #35]](‐
3158         https://github.com/PJK/libcbor/issues/35)
3159
3160       • Fixed         MSVC        compatibility        [[Fixes        #31]](‐
3161         https://github.com/PJK/libcbor/issues/31)
3162
3163       • Fixed   and    improved    half-float    encoding    [[Fixes    #5](‐
3164         https://github.com/PJK/libcbor/issues/5),                     [#11](‐
3165         https://github.com/PJK/libcbor/issues/11)]
3166
3167   0.4.0 (2015-12-25)
3168       Breaks build & header compatibility due to:
3169
3170       • Improved build configuration and feature check macros
3171
3172       • Endianess configuration fixes (by Erwin Kroon and David Grigsby)
3173
3174       • pkg-config compatibility (by Vincent Bernat)
3175
3176       • enable use of versioned SONAME (by Vincent Bernat)
3177
3178       • better fuzzer (wasn't random until now, ooops)
3179
3180   0.3.1 (2015-05-21)
3181       • documentation and comments improvements, mostly for the API reference
3182
3183   0.3.0 (2015-05-21)
3184       • Fixes, polishing, niceties across the code base
3185
3186       • Updated examples
3187
3188cbor_copy
3189
3190cbor_build_negint8, 16, 32, 64, matching asserts
3191
3192cbor_build_stringn
3193
3194cbor_build_tag
3195
3196cbor_build_float2, ...
3197
3198   0.2.1 (2015-05-17)
3199       • C99 support
3200
3201   0.2.0 (2015-05-17)
3202cbor_ctrl_bool -> cbor_ctrl_is_bool
3203
3204       • Added cbor_array_allocated & map equivalent
3205
3206       • Overhauled endianess conversion - ARM now works as expected
3207
3208       • 'sort.c' example added
3209
3210       • Significantly improved and doxyfied documentation
3211
3212   0.1.0 (2015-05-06)
3213       The initial release, yay!
3214
3215   Development
3216   Vision and principles
3217       Consistency and coherence are one of the key  characteristics  of  good
3218       software.   While the reality is never black and white, it is important
3219       libcbor contributors are working towards the same high-level goal. This
3220       document  attempts  to  set out the basic principles of libcbor and the
3221       rationale behind them. If you are contributing to libcbor or looking to
3222       evaluate whether libcbor is the right choice for your project, it might
3223       be worthwhile to skim through the section below.
3224
3225   Mission statement
3226       libcbor is the compact, full-featured, and safe CBOR library that works
3227       everywhere.
3228
3229   Goals
3230   RFC-conformance and full feature support
3231       Anything the standard allows, libcbor can do.
3232
3233       Why?  Because conformance and interoperability is the point of defining
3234       standards. Clients expect the support to be feature-complete and  there
3235       is no significant complexity reduction that can be achieved by slightly
3236       cutting corners, which means that the incremental cost of full RFC sup‐
3237       port  is comparatively small over "almost-conformance" seen in many al‐
3238       ternatives.
3239
3240   Safety
3241       Untrusted bytes from the network are the typical input.
3242
3243       Why? Because it is the client expectation. Vast  majority  of  security
3244       vulnerabilities  are violations of contracts -- in other words, bugs --
3245       anyway.
3246
3247   Self-containment
3248       libcbor has no runtime dependencies.
3249
3250       Why? Because any constraint imposed on libcbor has to be enforced tran‐
3251       sitively, which is difficult and leads to incompatibilities and distri‐
3252       bution issues, especially in IoT applications.
3253
3254   Portability
3255       If you can compile C for it, libcbor will work there.
3256
3257       Why? Lowest-common-denominator solution for system-level and IoT  soft‐
3258       ware  was  the original niche of libcbor. Users who rely on libcbor ex‐
3259       pect future updates to work on their target platform.
3260
3261   Stable and predictable API
3262       libcbor will not break without a warning.
3263
3264       Why? Industry-standard versioning is a basic  requirement  for  produc‐
3265       tion-quality  software. This is especially relevant in IoT environments
3266       where updates may be costly.
3267
3268   Performance
3269       libcbor is fast and resource-efficient by design
3270
3271       Why? Because the main maintainer is an avid hater of slow bloated soft‐
3272       ware.  Who wouldn't want more bang per their electricity buck?
3273
3274   Non-goals
3275          • Convenience  --  libcbor only provides the minimum surface to make
3276            it usable
3277
3278          • FFI/SWIG/interop support -- libcbor is primarily a C library for C
3279            clients
3280
3281          • One-off  usecases  support -- although there are primitives to re‐
3282            use, the basic assumption is that most clients want most  of  CBOR
3283            features
3284
3285   Development dependencies
3286CMocka (testing)
3287
3288Python and pip (Sphinx platform)
3289
3290Doxygen
3291
3292Sphinx (documentation)
3293
3294       • There are some Ruby scripts in misc
3295
3296Valgrind (memory correctness & profiling)
3297
3298GCOV/LCOV (test coverage)
3299
3300clang-format
3301
3302   Installing sphinx
3303          pip install sphinx
3304          pip install sphinx_rtd_theme
3305          pip install breathe
3306          pip install https://github.com/lepture/python-livereload/archive/master.zip
3307          pip install sphinx-autobuild
3308
3309       Further  instructions  on configuring advanced features can be found at
3310       http://read-the-docs.readthedocs.org/en/latest/install.html.
3311
3312   Live preview of docs
3313          cd doc
3314          make livehtml
3315
3316   Set up git hooks
3317       A catch-all git hook that runs clang-format and automatically refreshes
3318       the GH pages  contents located in docs can be symlinked:
3319
3320          ln -sf $(pwd)/misc/hooks/pre-commit .git/hooks
3321
3322   Testing and code coverage
3323       Please refer to tests
3324

AUTHOR

3326       Pavel Kalvoda
3327
3329       2021 - 2020, Pavel Kalvoda
3330
3331
3332
3333
33340.7                              Jan 26, 2021                       LIBCBOR(1)
Impressum