1LIBCBOR(1) libcbor LIBCBOR(1)
2
6 libcbor - libcbor Documentation
7 Documentation for version 0.5.0, updated on Feb 01, 2019.
9
11 libcbor is a C library for parsing and generating CBOR, the gen‐
12 eral-purpose schema-less binary data format.
13 Main features
15 · Complete RFC conformance [1]
17 · Robust C99 implementation
19 · Layered architecture offers both control and convenience
21 · Flexible memory management
23 · No shared global state - threading friendly [2]
25 · Proper handling of UTF-8
27 · Full support for streams & incremental processing
29 · Extensive documentation and test suite
31 · No runtime dependencies, small footprint
33 [1] See rfc_conformance
35 [2] With the exception of custom memory allocators (see api/item_ref‐
37 erence_counting)
38
40 Getting started
41 Pre-built Linux packages are distributed from the libcbor website.
42 OS X users can use Homebrew:
44 brew tap pjk/libcbor
46 brew install libcbor
47 For other platforms, you will need to compile it from source.
49 Building & installing libcbor
51 Prerequisites:
52 · C99 compiler
54 · CMake 2.8 or newer (might also be called cmakesetup, cmake-gui
56 or ccmake depending on the installed version and system)
57 · C build system CMake can target (make, Apple Xcode, MinGW,
59 ...)
60 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 Configuration options
69 A handful of configuration flags can be passed to cmake. The following
71 table lists libcbor compile-time directives and several important
72 generic flags.
73 ┌───────────────────┬──────────────────┬──────────────────┬──────────────────┐
75 │Option │ Meaning │ Default │ Possible values │
76 ├───────────────────┼──────────────────┼──────────────────┼──────────────────┤
77 │CMAKE_C_COMPILER │ C compiler to │ cc │ gcc, clang, │
78 │ │ use │ │ clang-3.5, ... │
79 ├───────────────────┼──────────────────┼──────────────────┼──────────────────┤
80 │CMAKE_INSTALL_PRE‐ │ Installation │ System-dependent │ /usr/local/lib, │
81 │FIX │ prefix │ │ ... │
82 ├───────────────────┼──────────────────┼──────────────────┼──────────────────┤
83 │HUGE_FUZZ │ Fuzz test with │ OFF │ ON, OFF │
84 │ │ 8GB of data │ │ │
85 ├───────────────────┼──────────────────┼──────────────────┼──────────────────┤
86 │SANE_MALLOC │ Assume malloc │ OFF │ ON, OFF │
87 │ │ will refuse │ │ │
88 │ │ unreasonable │ │ │
89 │ │ allocations │ │ │
90 ├───────────────────┼──────────────────┼──────────────────┼──────────────────┤
91 │COVERAGE │ Generate test │ OFF │ ON, OFF │
92 │ │ coverage instru‐ │ │ │
93 │ │ mentation │ │ │
94 ├───────────────────┼──────────────────┼──────────────────┼──────────────────┤
95 │WITH_TESTS │ Build unit tests │ OFF │ ON, OFF │
96 │ │ (see develop‐ │ │ │
97 │ │ ment) │ │ │
98 └───────────────────┴──────────────────┴──────────────────┴──────────────────┘
99 The following configuration options will also be defined as macros[#]_
101 in <cbor/common.h> and can therefore be used in client code:
102 ┌────────────────────┬──────────────────┬─────────┬─────────────────┐
104 │Option │ Meaning │ Default │ Possible values │
105 ├────────────────────┼──────────────────┼─────────┼─────────────────┤
106 │CBOR_CUS‐ │ Enable custom │ OFF │ ON, OFF │
107 │TOM_ALLOC │ allocator sup‐ │ │ │
108 │ │ port │ │ │
109 ├────────────────────┼──────────────────┼─────────┼─────────────────┤
110 │CBOR_PRETTY_PRINTER │ Include a │ ON │ ON, OFF │
111 │ │ pretty-printing │ │ │
112 │ │ routine │ │ │
113 ├────────────────────┼──────────────────┼─────────┼─────────────────┤
114 │CBOR_BUFFER_GROWTH │ Factor for buf‐ │ 2 │ Decimals > 1 │
115 │ │ fer growth & │ │ │
116 │ │ shrinking │ │ │
117 └────────────────────┴──────────────────┴─────────┴─────────────────┘
118 [1] ON & OFF will be translated to 1 and 0 using cmakedefine.
120 If you want to pass other custom configuration options, please
122 refer to http://www.cmake.org/Wiki/CMake_Useful_Variables.
123 Building using make
125 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 cd $(mktemp -d /tmp/cbor_build.XXXX)
133 Now, assuming you are in the directory where you want to build, execute
135 the following to configure the build and run make
136 cmake -DCMAKE_BUILD_TYPE=Release path_to_libcbor_dir
138 make cbor cbor_shared
139 Both the shared (libcbor.so) and the static (libcbor.a) libraries
141 should now be in the src subdirectory.
142 In order to install the libcbor headers and libraries, the usual
144 make install
146 is what your're looking for. Root permissions are required on most sys‐
148 tems when using the default installation prefix.
149 Portability
151 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 libcbor is known to successfully work on ARM Android devices.
159 Cross-compilation is possible with arm-linux-gnueabi-gcc.
160 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 You can verify that everything has been set up properly by creating a
167 file with the following contents
168 #include <cbor.h>
170 #include <stdio.h>
171 int main(int argc, char * argv[])
173 {
174 printf("Hello from libcbor %s\n", CBOR_VERSION);
175 }
176 and compiling it
178 cc hello_cbor.c -lcbor -o hello_cbor
180 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
183 objects:
184 cc $(pkg-config --cflags libcbor) hello_cbor.c $(pkg-config --libs libcbor) -o hello_cbor
186 MinGW build instructions
188 Prerequisites:
189 · MinGW
191 · CMake GUI
193 First of all, create a folder that will be used for the output. For
195 this demonstration, we will use cbor_out. Start CMake and select the
196 source path and the destination folder. [image]
197 Then hit the 'Configure' button. You will be prompted to select the
199 build system: [image]
200 Choose MinGW and confirm.
202 NOTE:
204 If you select Visual Studio at this point, a MSVC project will be
205 generated for you. This is useful if you just want to browse through
206 the source code.
207 You can then adjust the build options. The defaults will work just
209 fine. Hit 'Generate' when you are done. [image]
210 You can then adjust the build options. The defaults will work just
212 fine. Hit 'Generate' when you are done.
213 Open the shell, navigate to the output directory, and run mingw32-make
215 cbor cbor_shared. [image]
216 libcbor will be built and your .dll should be ready at this point
218 [image]
219 Feel free to also try building and running some of the examples, e.g.
221 mingw32-make sort [image]
222 Troubleshooting
224 cbor.h not found: The headers directory is probably not in your include
225 path. First, verify the installation location by checking the installa‐
226 tion log. If you used make, it will look something like
227 ...
229 -- Installing: /usr/local/include/cbor
230 -- Installing: /usr/local/include/cbor/callbacks.h
231 -- Installing: /usr/local/include/cbor/encoding.h
232 ...
233 Make sure that CMAKE_INSTALL_PREFIX (if you provided it) was correct.
235 Including the path path during compilation should suffice, e.g.:
236 cc -I/usr/local/include hello_cbor.c -lcbor -o hello_cbor
238 cannot find -lcbor during linking: Most likely the same problem as
240 before. Include the installation directory in the linker shared path
241 using -R, e.g.:
242 cc -Wl,-rpath,/usr/local/lib -lcbor -o hello_cbor
244 shared library missing during execution: Verify the linkage using ldd,
246 otool, or similar and adjust the compilation directives accordingly:
247 ⇒ ldd hello_cbor
249 linux-vdso.so.1 => (0x00007ffe85585000)
250 libcbor.so => /usr/local/lib/libcbor.so (0x00007f9af69da000)
251 libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f9af65eb000)
252 /lib64/ld-linux-x86-64.so.2 (0x00007f9af6be9000)
253 compilation failed: If your compiler supports C99 yet the compilation
255 has failed, please report the issue to the issue tracker.
256 Usage & preliminaries
258 Version information
259 libcbor exports its version using three self-explanatory macros:
260 · CBOR_MAJOR_VERSION
262 · CBOR_MINOR_VERSION
264 · CBOR_PATCH_VERSION
266 The CBOR_VERSION is a string concatenating these three identifiers into
268 one (e.g. 0.2.0).
269 In order to simplify version comparisons, the version is also exported
271 as
272 #define CBOR_HEX_VERSION ((CBOR_MAJOR_VERSION << 16) | (CBOR_MINOR_VERSION << 8) | CBOR_PATCH_VERSION)
274 Since macros are difficult to work with through FFIs, the same informa‐
276 tion is also available through three uint8_t constants, namely
277 · cbor_major_version
279 · cbor_minor_version
281 · cbor_patch_version
283 Headers to include
285 The cbor.h header includes all the symbols. If, for any reason, you
286 don't want to include all the exported symbols, feel free to use just
287 some of the cbor/*.h headers:
288 · cbor/arrays.h - api/type_4
290 · cbor/bytestrings.h - api/type_2
292 · cbor/callbacks.h - Callbacks used for streaming/decoding
294 · cbor/common.h - Common utilities - always transitively included
296 · cbor/data.h - Data types definitions - always transitively
298 included
299 · cbor/encoding.h - Streaming encoders for streaming/encoding
301 · cbor/floats_ctrls.h - api/type_7
303 · cbor/ints.h - api/type_0_1
305 · cbor/maps.h - api/type_5
307 · cbor/serialization.h - High level serialization such as cbor_seri‐
309 alize()
310 · cbor/streaming.h - Home of cbor_stream_decode()
312 · cbor/strings.h - api/type_3
314 · cbor/tags.h - api/type_6
316 Using libcbor
318 If you want to get more familiar with CBOR, we recommend the cbor.io
319 website. Once you get the grasp of what is it CBOR does, the examples
320 (located in the examples directory) should give you a good feel of the
321 API. The API documentation should then provide with all the information
322 you may need.
323 Creating and serializing items
325 #include "cbor.h"
327 #include <stdio.h>
328 int main(int argc, char * argv[])
330 {
331 /* Preallocate the map structure */
332 cbor_item_t * root = cbor_new_definite_map(2);
333 /* Add the content */
334 cbor_map_add(root, (struct cbor_pair) {
335 .key = cbor_move(cbor_build_string("Is CBOR awesome?")),
336 .value = cbor_move(cbor_build_bool(true))
337 });
338 cbor_map_add(root, (struct cbor_pair) {
339 .key = cbor_move(cbor_build_uint8(42)),
340 .value = cbor_move(cbor_build_string("Is the answer"))
341 });
342 /* Output: `length` bytes of data in the `buffer` */
343 unsigned char * buffer;
344 size_t buffer_size, length = cbor_serialize_alloc(root, &buffer, &buffer_size);
345 fwrite(buffer, 1, length, stdout);
347 free(buffer);
348 fflush(stdout);
350 cbor_decref(&root);
351 }
352 Reading serialized data
354 #include "cbor.h"
356 #include <stdio.h>
357 /*
359 * Reads data from a file. Example usage:
360 * $ ./examples/readfile examples/data/nested_array.cbor
361 */
362 int main(int argc, char * argv[])
364 {
365 FILE * f = fopen(argv[1], "rb");
366 fseek(f, 0, SEEK_END);
367 size_t length = (size_t)ftell(f);
368 fseek(f, 0, SEEK_SET);
369 unsigned char * buffer = malloc(length);
370 fread(buffer, length, 1, f);
371 /* Assuming `buffer` contains `info.st_size` bytes of input data */
373 struct cbor_load_result result;
374 cbor_item_t * item = cbor_load(buffer, length, &result);
375 /* Pretty-print the result */
376 cbor_describe(item, stdout);
377 fflush(stdout);
378 /* Deallocate the result */
379 cbor_decref(&item);
380 fclose(f);
382 }
383 Using the streaming parser
385 #include "cbor.h"
387 #include <stdio.h>
388 #include <string.h>
389 /*
391 * Illustrates how one might skim through a map (which is assumed to have
392 * string keys and values only), looking for the value of a specific key
393 *
394 * Use the examples/data/map.cbor input to test this.
395 */
396 const char * key = "a secret key";
398 bool key_found = false;
399 void find_string(void * _ctx, cbor_data buffer, size_t len)
401 {
402 if (key_found) {
403 printf("Found the value: %*s\n", (int) len, buffer);
404 key_found = false;
405 } else if (len == strlen(key)) {
406 key_found = (memcmp(key, buffer, len) == 0);
407 }
408 }
409 int main(int argc, char * argv[])
411 {
412 FILE * f = fopen(argv[1], "rb");
413 fseek(f, 0, SEEK_END);
414 size_t length = (size_t)ftell(f);
415 fseek(f, 0, SEEK_SET);
416 unsigned char * buffer = malloc(length);
417 fread(buffer, length, 1, f);
418 struct cbor_callbacks callbacks = cbor_empty_callbacks;
420 struct cbor_decoder_result decode_result;
421 size_t bytes_read = 0;
422 callbacks.string = find_string;
423 while (bytes_read < length) {
424 decode_result = cbor_stream_decode(buffer + bytes_read,
425 length - bytes_read,
426 &callbacks, NULL);
427 bytes_read += decode_result.read;
428 }
429 fclose(f);
431 }
432 API
434 The data API is centered around cbor_item_t, a generic handle for any
435 CBOR item. There are functions to
436 · create items,
438 · set items' data,
440 · parse serialized data into items,
442 · manage, move, and links item together.
444 The single most important thing to keep in mind is: cbor_item_t is an
446 opaque type and should only be manipulated using the appropriate func‐
447 tions! Think of it as an object.
448 The libcbor API closely follows the semantics outlined by CBOR stan‐
450 dard. This part of the documentation provides a short overview of the
451 CBOR constructs, as well as a general introduction to the libcbor API.
452 Remaining reference can be found in the following files structured by
453 data types.
454 The API is designed to allow both very tight control & flexibility and
456 general convenience with sane defaults. [1] For example, client with
457 very specific requirements (constrained environment, custom application
458 protocol built on top of CBOR, etc.) may choose to take full control
459 (and responsibility) of memory and data structures management by inter‐
460 acting directly with the decoder. Other clients might want to take con‐
461 trol of specific aspects (streamed collections, hash maps storage), but
462 leave other responsibilities to libcbor. More general clients might
463 prefer to be abstracted away from all aforementioned details and only
464 be presented complete data structures.
465 libcbor provides
467 · stateless encoders and decoders
469 · encoding and decoding drivers, routines that coordinate encod‐
471 ing and decoding of complex structures
472 · data structures to represent and transform CBOR structures
474 · routines for building and manipulating these structures
476 · utilities for inspection and debugging
478 Types of items
480 Every cbor_item_t has a cbor_type associated with it - these constants
481 correspond to the types specified by the CBOR standard:
482 WARNING:
484 doxygenenum: Cannot find file: /builddir/build/BUILD/libc‐
485 bor-0.5.0/doc/build/doxygen/xml/index.xml
486 To find out the type of an item, one can use
488 WARNING:
490 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
491 bor-0.5.0/doc/build/doxygen/xml/index.xml
492 Please note the distinction between functions like cbor_isa_uint() and
494 cbor_is_int(). The following functions work solely with the major type
495 value.
496 Binary queries
498 Alternatively, there are functions to query each particular type.
499 WARNING:
501 Passing an invalid cbor_item_t reference to any of these functions
502 results in undefined behavior.
503 WARNING:
505 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
506 bor-0.5.0/doc/build/doxygen/xml/index.xml
507 WARNING:
509 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
510 bor-0.5.0/doc/build/doxygen/xml/index.xml
511 WARNING:
513 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
514 bor-0.5.0/doc/build/doxygen/xml/index.xml
515 WARNING:
517 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
518 bor-0.5.0/doc/build/doxygen/xml/index.xml
519 WARNING:
521 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
522 bor-0.5.0/doc/build/doxygen/xml/index.xml
523 WARNING:
525 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
526 bor-0.5.0/doc/build/doxygen/xml/index.xml
527 WARNING:
529 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
530 bor-0.5.0/doc/build/doxygen/xml/index.xml
531 WARNING:
533 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
534 bor-0.5.0/doc/build/doxygen/xml/index.xml
535 Logical queries
537 These functions provide information about the item type from a more
538 high-level perspective
539 WARNING:
541 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
542 bor-0.5.0/doc/build/doxygen/xml/index.xml
543 WARNING:
545 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
546 bor-0.5.0/doc/build/doxygen/xml/index.xml
547 WARNING:
549 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
550 bor-0.5.0/doc/build/doxygen/xml/index.xml
551 WARNING:
553 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
554 bor-0.5.0/doc/build/doxygen/xml/index.xml
555 WARNING:
557 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
558 bor-0.5.0/doc/build/doxygen/xml/index.xml
559 Memory management and reference counting
561 Due to the nature of its domain libcbor will need to work with heap
562 memory. The stateless decoder and encoder don't allocate any memory.
563 If you have specific requirements, you should consider rolling your own
565 driver for the stateless API.
566 Using custom allocator
568 libcbor gives you with the ability to provide your own implementations
569 of malloc, realloc, and free. This can be useful if you are using a
570 custom allocator throughout your application, or if you want to imple‐
571 ment custom policies (e.g. tighter restrictions on the amount of allo‐
572 cated memory).
573 In order to use this feature, libcbor has to be compiled with the
575 appropriate flags. You can verify the configuration using the CBOR_CUS‐
576 TOM_ALLOC macro. A simple usage might be as follows:
577 #if CBOR_CUSTOM_ALLOC
579 cbor_set_allocs(malloc, realloc, free);
580 #else
581 #error "libcbor built with support for custom allocation is required"
582 #endif
583 WARNING:
585 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
586 bor-0.5.0/doc/build/doxygen/xml/index.xml
587 Reference counting
589 As CBOR items may require complex cleanups at the end of their life‐
590 time, there is a reference counting mechanism in place. This also
591 enables very simple GC when integrating libcbor into managed environ‐
592 ment. Every item starts its life (by either explicit creation, or as a
593 result of parsing) with reference count set to 1. When the refcount
594 reaches zero, it will be destroyed.
595 Items containing nested items will be destroyed recursively - refcount
597 of every nested item will be decreased by one.
598 The destruction is synchronous and renders any pointers to items with
600 refcount zero invalid immediately after calling the cbor_decref().
601 WARNING:
603 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
604 bor-0.5.0/doc/build/doxygen/xml/index.xml
605 WARNING:
607 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
608 bor-0.5.0/doc/build/doxygen/xml/index.xml
609 WARNING:
611 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
612 bor-0.5.0/doc/build/doxygen/xml/index.xml
613 WARNING:
615 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
616 bor-0.5.0/doc/build/doxygen/xml/index.xml
617 WARNING:
619 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
620 bor-0.5.0/doc/build/doxygen/xml/index.xml
621 WARNING:
623 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
624 bor-0.5.0/doc/build/doxygen/xml/index.xml
625 Decoding
627 The following diagram illustrates the relationship among different
628 parts of libcbor from the decoding standpoint.
629 ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
631 │ │
632 │ Client application │
633 │ │
634 │ ┌────────────────────────────────────────────┘
635 │ │ ↕
636 │ │ ┌──────────────────────────────────────────┐
637 │ │ │ │
638 │ │ │ Manipulation routines │
639 │ │ │ │
640 │ ┌─────────────────────────────────────┘ └──────────────────────────────────────────┘
641 │ │ ↑ ↑ ↑ ↑
642 │ │ │ │ ┌─────────────╫──────────┬───────────────────┴─┐
643 │ │ │ CDS │ ║ │ │
644 │ │ │ │ PDS ║ PDS PDS
645 │ │ ↓ ↓ ↓ ↓ ↓ ↓
646 │ │ ┌─────────────────┐ ┌────────────────────┐ ┌────────────────────────────┐
647 │ │ │ │ │ │ │ │
648 │ │ │ Custom driver │ ↔ │ Streaming driver │ ↔ │ Default driver │ ↔ CD
649 │ │ │ │ │ │ │ │
650 └───────────┘ └─────────────────┘ └────────────────────┘ └────────────────────────────┘
651 ↕ ↕ ↕ ↕
652 ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
653 │ │
654 │ Stateless event─driven decoder │
655 │ │
656 └──────────────────────────────────────────────────────────────────────────────────────────────┘
657 (PSD = Provided Data Structures, CDS = Custom Data Structures)
659 This section will deal with the API that is labeled as the "Default
661 driver" in the diagram. That is, routines that decode complete libcbor
662 data items
663 WARNING:
665 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
666 bor-0.5.0/doc/build/doxygen/xml/index.xml
667 Associated data structures
669 WARNING:
670 doxygenenum: Cannot find file: /builddir/build/BUILD/libc‐
671 bor-0.5.0/doc/build/doxygen/xml/index.xml
672 WARNING:
674 doxygenstruct: Cannot find file: /builddir/build/BUILD/libc‐
675 bor-0.5.0/doc/build/doxygen/xml/index.xml
676 WARNING:
678 doxygenstruct: Cannot find file: /builddir/build/BUILD/libc‐
679 bor-0.5.0/doc/build/doxygen/xml/index.xml
680 Encoding
682 The easiest way to encode data items is using the cbor_serialize() or
683 cbor_serialize_alloc() functions:
684 WARNING:
686 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
687 bor-0.5.0/doc/build/doxygen/xml/index.xml
688 WARNING:
690 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
691 bor-0.5.0/doc/build/doxygen/xml/index.xml
692 Type-specific serializers
694 In case you know the type of the item you want to serialize beforehand,
695 you can use one of the type-specific serializers.
696 NOTE:
698 Unless compiled in debug mode, these do not verify the type. Passing
699 an incorrect item will result in an undefined behavior.
700 WARNING:
702 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
703 bor-0.5.0/doc/build/doxygen/xml/index.xml
704 WARNING:
706 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
707 bor-0.5.0/doc/build/doxygen/xml/index.xml
708 WARNING:
710 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
711 bor-0.5.0/doc/build/doxygen/xml/index.xml
712 WARNING:
714 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
715 bor-0.5.0/doc/build/doxygen/xml/index.xml
716 WARNING:
718 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
719 bor-0.5.0/doc/build/doxygen/xml/index.xml
720 WARNING:
722 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
723 bor-0.5.0/doc/build/doxygen/xml/index.xml
724 WARNING:
726 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
727 bor-0.5.0/doc/build/doxygen/xml/index.xml
728 WARNING:
730 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
731 bor-0.5.0/doc/build/doxygen/xml/index.xml
732 Types 0 & 1 – Positive and negative integers
734 CBOR has two types of integers – positive (which may be effectively
735 regarded as unsigned), and negative. There are four possible widths for
736 an integer – 1, 2, 4, or 8 bytes. These are represented by
737 WARNING:
739 doxygenenum: Cannot find file: /builddir/build/BUILD/libc‐
740 bor-0.5.0/doc/build/doxygen/xml/index.xml
741 Type 0 - positive integers
743 ┌────────────────────────┬────────────────────────────┐
744 │Corresponding cbor_type │ CBOR_TYPE_UINT │
745 ├────────────────────────┼────────────────────────────┤
746 │Number of allocations │ One per lifetime │
747 ├────────────────────────┼────────────────────────────┤
748 │Storage requirements │ sizeof(cbor_item_t) + │
749 │ │ sizeof(uint*_t) │
750 └────────────────────────┴────────────────────────────┘
751 Note: once a positive integer has been created, its width cannot be
753 changed.
754 Type 1 - negative integers
756 ┌────────────────────────┬────────────────────────────┐
757 │Corresponding cbor_type │ CBOR_TYPE_NEGINT │
758 ├────────────────────────┼────────────────────────────┤
759 │Number of allocations │ One per lifetime │
760 ├────────────────────────┼────────────────────────────┤
761 │Storage requirements │ sizeof(cbor_item_t) + │
762 │ │ sizeof(uint*_t) │
763 └────────────────────────┴────────────────────────────┘
764 Note: once a positive integer has been created, its width cannot be
766 changed.
767 Type 0 & 1
769 Due to their largely similar semantics, the following functions can be
770 used for both Type 0 and Type 1 items. One can convert between them
771 freely using the conversion functions.
772 Actual Type of the integer can be checked using item types API.
774 An integer item is created with one of the four widths. Because inte‐
776 gers' storage is bundled together with the handle, the width cannot be
777 changed over its lifetime.
778 WARNING:
780 Due to the fact that CBOR negative integers represent integers in
781 the range [-1, -2^N], cbor_set_uint API is somewhat counter-intu‐
782 itive as the resulting logical value is 1 less. This behavior is
783 necessary in order to permit uniform manipulation with the full
784 range of permitted values. For example, the following snippet
785 cbor_item_t * item = cbor_new_int8();
787 cbor_mark_negint(item);
788 cbor_set_uint8(0);
789 will produce an item with the logical value of -1. There is, how‐
791 ever, an upside to this as well: There is only one representation of
792 zero.
793 Building new items
795 WARNING:
796 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
797 bor-0.5.0/doc/build/doxygen/xml/index.xml
798 WARNING:
800 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
801 bor-0.5.0/doc/build/doxygen/xml/index.xml
802 WARNING:
804 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
805 bor-0.5.0/doc/build/doxygen/xml/index.xml
806 WARNING:
808 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
809 bor-0.5.0/doc/build/doxygen/xml/index.xml
810 Retrieving values
812 WARNING:
813 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
814 bor-0.5.0/doc/build/doxygen/xml/index.xml
815 WARNING:
817 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
818 bor-0.5.0/doc/build/doxygen/xml/index.xml
819 WARNING:
821 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
822 bor-0.5.0/doc/build/doxygen/xml/index.xml
823 WARNING:
825 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
826 bor-0.5.0/doc/build/doxygen/xml/index.xml
827 Setting values
829 WARNING:
830 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
831 bor-0.5.0/doc/build/doxygen/xml/index.xml
832 WARNING:
834 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
835 bor-0.5.0/doc/build/doxygen/xml/index.xml
836 WARNING:
838 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
839 bor-0.5.0/doc/build/doxygen/xml/index.xml
840 WARNING:
842 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
843 bor-0.5.0/doc/build/doxygen/xml/index.xml
844 Dealing with width
846 WARNING:
847 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
848 bor-0.5.0/doc/build/doxygen/xml/index.xml
849 Dealing with signedness
851 WARNING:
852 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
853 bor-0.5.0/doc/build/doxygen/xml/index.xml
854 WARNING:
856 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
857 bor-0.5.0/doc/build/doxygen/xml/index.xml
858 Creating new items
860 WARNING:
861 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
862 bor-0.5.0/doc/build/doxygen/xml/index.xml
863 WARNING:
865 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
866 bor-0.5.0/doc/build/doxygen/xml/index.xml
867 WARNING:
869 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
870 bor-0.5.0/doc/build/doxygen/xml/index.xml
871 WARNING:
873 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
874 bor-0.5.0/doc/build/doxygen/xml/index.xml
875 Type 2 – Byte strings
877 CBOR byte strings are just (ordered) series of bytes without further
878 interpretation (unless there is a tag). Byte string's length may or may
879 not be known during encoding. These two kinds of byte strings can be
880 distinguished using cbor_bytestring_is_definite() and
881 cbor_bytestring_is_indefinite() respectively.
882 In case a byte string is indefinite, it is encoded as a series of defi‐
884 nite byte strings. These are called "chunks". For example, the encoded
885 item
886 0xf5 Start indefinite byte string
888 0x41 Byte string (1B long)
889 0x00
890 0x41 Byte string (1B long)
891 0xff
892 0xff "Break" control token
893 represents two bytes, 0x00 and 0xff. This on one hand enables streaming
895 messages even before they are fully generated, but on the other hand it
896 adds more complexity to the client code.
897 ┌───────────────────────────┬────────────────────────────┐
899 │Corresponding cbor_type │ CBOR_TYPE_BYTESTRING │
900 ├───────────────────────────┼────────────────────────────┤
901 │Number of allocations │ One plus any manipulations │
902 │(definite) │ with the data │
903 ├───────────────────────────┼────────────────────────────┤
904 │Number of allocations │ One plus logarithmically │
905 │(indefinite) │ many reallocations rela‐ │
906 │ │ tive to chunk count │
907 ├───────────────────────────┼────────────────────────────┤
908 │Storage requirements (def‐ │ sizeof(cbor_item_t) + │
909 │inite) │ length(handle) │
910 ├───────────────────────────┼────────────────────────────┤
911 │Storage requirements │ sizeof(cbor_item_t) * (1 + │
912 │(indefinite) │ chunk_count) + chunks │
913 └───────────────────────────┴────────────────────────────┘
914 Streaming indefinite byte strings
916 Please refer to /streaming.
917 Getting metadata
919 WARNING:
920 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
921 bor-0.5.0/doc/build/doxygen/xml/index.xml
922 WARNING:
924 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
925 bor-0.5.0/doc/build/doxygen/xml/index.xml
926 WARNING:
928 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
929 bor-0.5.0/doc/build/doxygen/xml/index.xml
930 WARNING:
932 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
933 bor-0.5.0/doc/build/doxygen/xml/index.xml
934 Reading data
936 WARNING:
937 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
938 bor-0.5.0/doc/build/doxygen/xml/index.xml
939 WARNING:
941 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
942 bor-0.5.0/doc/build/doxygen/xml/index.xml
943 Creating new items
945 WARNING:
946 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
947 bor-0.5.0/doc/build/doxygen/xml/index.xml
948 WARNING:
950 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
951 bor-0.5.0/doc/build/doxygen/xml/index.xml
952 Building items
954 WARNING:
955 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
956 bor-0.5.0/doc/build/doxygen/xml/index.xml
957 Manipulating existing items
959 WARNING:
960 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
961 bor-0.5.0/doc/build/doxygen/xml/index.xml
962 WARNING:
964 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
965 bor-0.5.0/doc/build/doxygen/xml/index.xml
966 Type 3 – UTF-8 strings
968 CBOR strings work in much the same ways as type_2.
969 ┌───────────────────────────┬────────────────────────────┐
971 │Corresponding cbor_type │ CBOR_TYPE_STRING │
972 ├───────────────────────────┼────────────────────────────┤
973 │Number of allocations │ One plus any manipulations │
974 │(definite) │ with the data │
975 ├───────────────────────────┼────────────────────────────┤
976 │Number of allocations │ One plus logarithmically │
977 │(indefinite) │ many reallocations rela‐ │
978 │ │ tive to chunk count │
979 ├───────────────────────────┼────────────────────────────┤
980 │Storage requirements (def‐ │ sizeof(cbor_item_t) + │
981 │inite) │ length(handle) │
982 ├───────────────────────────┼────────────────────────────┤
983 │Storage requirements │ sizeof(cbor_item_t) * (1 + │
984 │(indefinite) │ chunk_count) + chunks │
985 └───────────────────────────┴────────────────────────────┘
986 Streaming indefinite strings
988 Please refer to /streaming.
989 UTF-8 encoding validation
991 libcbor considers UTF-8 encoding validity to be a part of the
992 well-formedness notion of CBOR and therefore invalid UTF-8 strings will
993 be rejected by the parser. Strings created by the user are not checked.
994 Getting metadata
996 WARNING:
997 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
998 bor-0.5.0/doc/build/doxygen/xml/index.xml
999 WARNING:
1001 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1002 bor-0.5.0/doc/build/doxygen/xml/index.xml
1003 WARNING:
1005 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1006 bor-0.5.0/doc/build/doxygen/xml/index.xml
1007 WARNING:
1009 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1010 bor-0.5.0/doc/build/doxygen/xml/index.xml
1011 Reading data
1013 WARNING:
1014 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1015 bor-0.5.0/doc/build/doxygen/xml/index.xml
1016 WARNING:
1018 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1019 bor-0.5.0/doc/build/doxygen/xml/index.xml
1020 Creating new items
1022 WARNING:
1023 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1024 bor-0.5.0/doc/build/doxygen/xml/index.xml
1025 WARNING:
1027 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1028 bor-0.5.0/doc/build/doxygen/xml/index.xml
1029 Building items
1031 WARNING:
1032 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1033 bor-0.5.0/doc/build/doxygen/xml/index.xml
1034 Manipulating existing items
1036 WARNING:
1037 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1038 bor-0.5.0/doc/build/doxygen/xml/index.xml
1039 WARNING:
1041 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1042 bor-0.5.0/doc/build/doxygen/xml/index.xml
1043 Type 4 – Arrays
1045 CBOR arrays, just like byte strings and strings, can be encoded either
1046 as definite, or as indefinite.
1047 ┌───────────────────────────┬────────────────────────────┐
1049 │Corresponding cbor_type │ CBOR_TYPE_ARRAY │
1050 ├───────────────────────────┼────────────────────────────┤
1051 │Number of allocations │ Two plus any manipulations │
1052 │(definite) │ with the data │
1053 ├───────────────────────────┼────────────────────────────┤
1054 │Number of allocations │ Two plus logarithmically │
1055 │(indefinite) │ many reallocations rela‐ │
1056 │ │ tive to additions │
1057 └───────────────────────────┴────────────────────────────┘
1058 │Storage requirements (def‐ │ (sizeof(cbor_item_t) + 1) │
1062 │inite) │ * size │
1063 ├───────────────────────────┼────────────────────────────┤
1064 │Storage requirements │ <= sizeof(cbor_item_t) + │
1065 │(indefinite) │ sizeof(cbor_item_t) * size │
1066 │ │ * BUFFER_GROWTH │
1067 └───────────────────────────┴────────────────────────────┘
1068 Examples
1070 0x9f Start indefinite array
1071 0x01 Unsigned integer 1
1072 0xff "Break" control token
1073 0x9f Start array, 1B length follows
1075 0x20 Unsigned integer 32
1076 ... 32 items follow
1077 Streaming indefinite arrays
1079 Please refer to /streaming.
1080 Getting metadata
1082 WARNING:
1083 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1084 bor-0.5.0/doc/build/doxygen/xml/index.xml
1085 WARNING:
1087 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1088 bor-0.5.0/doc/build/doxygen/xml/index.xml
1089 WARNING:
1091 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1092 bor-0.5.0/doc/build/doxygen/xml/index.xml
1093 WARNING:
1095 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1096 bor-0.5.0/doc/build/doxygen/xml/index.xml
1097 Reading data
1099 WARNING:
1100 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1101 bor-0.5.0/doc/build/doxygen/xml/index.xml
1102 WARNING:
1104 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1105 bor-0.5.0/doc/build/doxygen/xml/index.xml
1106 Creating new items
1108 WARNING:
1109 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1110 bor-0.5.0/doc/build/doxygen/xml/index.xml
1111 WARNING:
1113 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1114 bor-0.5.0/doc/build/doxygen/xml/index.xml
1115 Modifying items
1117 WARNING:
1118 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1119 bor-0.5.0/doc/build/doxygen/xml/index.xml
1120 WARNING:
1122 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1123 bor-0.5.0/doc/build/doxygen/xml/index.xml
1124 WARNING:
1126 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1127 bor-0.5.0/doc/build/doxygen/xml/index.xml
1128 Type 5 – Maps
1130 CBOR maps are the plain old associate hash maps known from JSON and
1131 many other formats and languages, with one exception: any CBOR data
1132 item can be a key, not just strings. This is somewhat unusual and you,
1133 as an application developer, should keep that in mind.
1134 Maps can be either definite or indefinite, in much the same way as
1136 type_4.
1137 ┌───────────────────────────┬────────────────────────────┐
1139 │Corresponding cbor_type │ CBOR_TYPE_MAP │
1140 ├───────────────────────────┼────────────────────────────┤
1141 │Number of allocations │ Two plus any manipulations │
1142 │(definite) │ with the data │
1143 ├───────────────────────────┼────────────────────────────┤
1144 │Number of allocations │ Two plus logarithmically │
1145 │(indefinite) │ many reallocations rela‐ │
1146 │ │ tive to additions │
1147 ├───────────────────────────┼────────────────────────────┤
1148 │Storage requirements (def‐ │ sizeof(cbor_pair) * size + │
1149 │inite) │ sizeof(cbor_item_t) │
1150 ├───────────────────────────┼────────────────────────────┤
1151 │Storage requirements │ <= sizeof(cbor_item_t) + │
1152 │(indefinite) │ sizeof(cbor_pair) * size * │
1153 │ │ BUFFER_GROWTH │
1154 └───────────────────────────┴────────────────────────────┘
1155 Streaming maps
1157 Please refer to /streaming.
1158 Getting metadata
1160 WARNING:
1161 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1162 bor-0.5.0/doc/build/doxygen/xml/index.xml
1163 WARNING:
1165 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1166 bor-0.5.0/doc/build/doxygen/xml/index.xml
1167 WARNING:
1169 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1170 bor-0.5.0/doc/build/doxygen/xml/index.xml
1171 WARNING:
1173 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1174 bor-0.5.0/doc/build/doxygen/xml/index.xml
1175 Reading data
1177 WARNING:
1178 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1179 bor-0.5.0/doc/build/doxygen/xml/index.xml
1180 Creating new items
1182 WARNING:
1183 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1184 bor-0.5.0/doc/build/doxygen/xml/index.xml
1185 WARNING:
1187 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1188 bor-0.5.0/doc/build/doxygen/xml/index.xml
1189 Modifying items
1191 WARNING:
1192 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1193 bor-0.5.0/doc/build/doxygen/xml/index.xml
1194 Type 6 – Semantic tags
1196 Tag are additional metadata that can be used to extend or specialize
1197 the meaning or interpretation of the other data items.
1198 For example, one might tag an array of numbers to communicate that it
1200 should be interpreted as a vector.
1201 Please consult the official IANA repository of CBOR tags before invent‐
1203 ing new ones.
1204 WARNING:
1206 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1207 bor-0.5.0/doc/build/doxygen/xml/index.xml
1208 WARNING:
1210 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1211 bor-0.5.0/doc/build/doxygen/xml/index.xml
1212 WARNING:
1214 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1215 bor-0.5.0/doc/build/doxygen/xml/index.xml
1216 WARNING:
1218 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1219 bor-0.5.0/doc/build/doxygen/xml/index.xml
1220 Type 7 – Floats & control tokens
1222 This type combines two completely unrelated types of items -- floating
1223 point numbers and special values such as true, false, null, etc. We
1224 refer to these special values as 'control values' or 'ctrls' for short
1225 throughout the code.
1226 Just like integers, they have different possible width (resulting in
1228 different value ranges and precisions).
1229 WARNING:
1231 doxygenenum: Cannot find file: /builddir/build/BUILD/libc‐
1232 bor-0.5.0/doc/build/doxygen/xml/index.xml
1233 ┌────────────────────────┬────────────────────────────┐
1235 │Corresponding cbor_type │ CBOR_TYPE_FLOAT_CTRL │
1236 ├────────────────────────┼────────────────────────────┤
1237 │Number of allocations │ One per lifetime │
1238 ├────────────────────────┼────────────────────────────┤
1239 │Storage requirements │ sizeof(cbor_item_t) + │
1240 │ │ 1/4/8 │
1241 └────────────────────────┴────────────────────────────┘
1242 Getting metadata
1244 WARNING:
1245 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1246 bor-0.5.0/doc/build/doxygen/xml/index.xml
1247 WARNING:
1249 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1250 bor-0.5.0/doc/build/doxygen/xml/index.xml
1251 WARNING:
1253 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1254 bor-0.5.0/doc/build/doxygen/xml/index.xml
1255 Reading data
1257 WARNING:
1258 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1259 bor-0.5.0/doc/build/doxygen/xml/index.xml
1260 WARNING:
1262 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1263 bor-0.5.0/doc/build/doxygen/xml/index.xml
1264 WARNING:
1266 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1267 bor-0.5.0/doc/build/doxygen/xml/index.xml
1268 WARNING:
1270 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1271 bor-0.5.0/doc/build/doxygen/xml/index.xml
1272 WARNING:
1274 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1275 bor-0.5.0/doc/build/doxygen/xml/index.xml
1276 Creating new items
1278 WARNING:
1279 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1280 bor-0.5.0/doc/build/doxygen/xml/index.xml
1281 WARNING:
1283 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1284 bor-0.5.0/doc/build/doxygen/xml/index.xml
1285 WARNING:
1287 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1288 bor-0.5.0/doc/build/doxygen/xml/index.xml
1289 WARNING:
1291 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1292 bor-0.5.0/doc/build/doxygen/xml/index.xml
1293 WARNING:
1295 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1296 bor-0.5.0/doc/build/doxygen/xml/index.xml
1297 WARNING:
1299 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1300 bor-0.5.0/doc/build/doxygen/xml/index.xml
1301 Building items
1303 WARNING:
1304 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1305 bor-0.5.0/doc/build/doxygen/xml/index.xml
1306 WARNING:
1308 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1309 bor-0.5.0/doc/build/doxygen/xml/index.xml
1310 WARNING:
1312 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1313 bor-0.5.0/doc/build/doxygen/xml/index.xml
1314 WARNING:
1316 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1317 bor-0.5.0/doc/build/doxygen/xml/index.xml
1318 WARNING:
1320 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1321 bor-0.5.0/doc/build/doxygen/xml/index.xml
1322 Manipulating existing items
1324 WARNING:
1325 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1326 bor-0.5.0/doc/build/doxygen/xml/index.xml
1327 WARNING:
1329 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1330 bor-0.5.0/doc/build/doxygen/xml/index.xml
1331 WARNING:
1333 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1334 bor-0.5.0/doc/build/doxygen/xml/index.xml
1335 WARNING:
1337 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1338 bor-0.5.0/doc/build/doxygen/xml/index.xml
1339 Half floats
1341 CBOR supports two bytes wide ("half-precision") floats which are not
1342 supported by the C language. libcbor represents them using float values
1343 throughout the API, which has important implications when manipulating
1344 these values.
1345 In particular, if a user uses some of the manipulation APIs (e.g.
1347 cbor_set_float2(), cbor_new_float2()) to introduce a value that doesn't
1348 have an exect half-float representation, the encoding semantics are
1349 given by cbor_encode_half() as follows:
1350 WARNING:
1352 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1353 bor-0.5.0/doc/build/doxygen/xml/index.xml
1354 [1] http://softwareengineering.vazexqi.com/files/pattern.html
1356 Streaming & indefinite items
1358 CBOR strings, byte strings, arrays, and maps can be encoded as indefi‐
1359 nite, meaning their length or size is not specified. Instead, they are
1360 divided into chunks (strings, byte strings), or explicitly terminated
1361 (arrays, maps).
1362 This is one of the most important (and due to poor implementations,
1364 underutilized) features of CBOR. It enables low-overhead streaming just
1365 about anywhere without dealing with channels or pub/sub mechanism. It
1366 is, however, important to recognize that CBOR streaming is not a sub‐
1367 stitute for Websockets [1] and similar technologies.
1368 [1] RFC 6455
1370 Decoding
1372 Another way to decode data using libcbor is to specify a callbacks that
1373 will be invoked when upon finding certain items in the input. This ser‐
1374 vice is provided by
1375 WARNING:
1377 doxygenfunction: Cannot find file: /builddir/build/BUILD/libc‐
1378 bor-0.5.0/doc/build/doxygen/xml/index.xml
1379 To get started, you might want to have a look at the simple streaming
1381 example:
1382 #include "cbor.h"
1384 #include <stdio.h>
1385 #include <string.h>
1386 /*
1388 * Illustrates how one might skim through a map (which is assumed to have
1389 * string keys and values only), looking for the value of a specific key
1390 *
1391 * Use the examples/data/map.cbor input to test this.
1392 */
1393 const char * key = "a secret key";
1395 bool key_found = false;
1396 void find_string(void * _ctx, cbor_data buffer, size_t len)
1398 {
1399 if (key_found) {
1400 printf("Found the value: %*s\n", (int) len, buffer);
1401 key_found = false;
1402 } else if (len == strlen(key)) {
1403 key_found = (memcmp(key, buffer, len) == 0);
1404 }
1405 }
1406 int main(int argc, char * argv[])
1408 {
1409 FILE * f = fopen(argv[1], "rb");
1410 fseek(f, 0, SEEK_END);
1411 size_t length = (size_t)ftell(f);
1412 fseek(f, 0, SEEK_SET);
1413 unsigned char * buffer = malloc(length);
1414 fread(buffer, length, 1, f);
1415 struct cbor_callbacks callbacks = cbor_empty_callbacks;
1417 struct cbor_decoder_result decode_result;
1418 size_t bytes_read = 0;
1419 callbacks.string = find_string;
1420 while (bytes_read < length) {
1421 decode_result = cbor_stream_decode(buffer + bytes_read,
1422 length - bytes_read,
1423 &callbacks, NULL);
1424 bytes_read += decode_result.read;
1425 }
1426 free(buffer);
1428 fclose(f);
1429 }
1430 The callbacks are defined by
1432 WARNING:
1434 doxygenstruct: Cannot find file: /builddir/build/BUILD/libc‐
1435 bor-0.5.0/doc/build/doxygen/xml/index.xml
1436 When building custom sets of callbacks, feel free to start from
1438 WARNING:
1440 doxygenvariable: Cannot find file: /builddir/build/BUILD/libc‐
1441 bor-0.5.0/doc/build/doxygen/xml/index.xml
1442 Related structures
1444 WARNING:
1445 doxygenenum: Cannot find file: /builddir/build/BUILD/libc‐
1446 bor-0.5.0/doc/build/doxygen/xml/index.xml
1447 WARNING:
1449 doxygenstruct: Cannot find file: /builddir/build/BUILD/libc‐
1450 bor-0.5.0/doc/build/doxygen/xml/index.xml
1451 Callback types definition
1453 WARNING:
1454 doxygentypedef: Cannot find file: /builddir/build/BUILD/libc‐
1455 bor-0.5.0/doc/build/doxygen/xml/index.xml
1456 WARNING:
1458 doxygentypedef: Cannot find file: /builddir/build/BUILD/libc‐
1459 bor-0.5.0/doc/build/doxygen/xml/index.xml
1460 WARNING:
1462 doxygentypedef: Cannot find file: /builddir/build/BUILD/libc‐
1463 bor-0.5.0/doc/build/doxygen/xml/index.xml
1464 WARNING:
1466 doxygentypedef: Cannot find file: /builddir/build/BUILD/libc‐
1467 bor-0.5.0/doc/build/doxygen/xml/index.xml
1468 WARNING:
1470 doxygentypedef: Cannot find file: /builddir/build/BUILD/libc‐
1471 bor-0.5.0/doc/build/doxygen/xml/index.xml
1472 WARNING:
1474 doxygentypedef: Cannot find file: /builddir/build/BUILD/libc‐
1475 bor-0.5.0/doc/build/doxygen/xml/index.xml
1476 WARNING:
1478 doxygentypedef: Cannot find file: /builddir/build/BUILD/libc‐
1479 bor-0.5.0/doc/build/doxygen/xml/index.xml
1480 WARNING:
1482 doxygentypedef: Cannot find file: /builddir/build/BUILD/libc‐
1483 bor-0.5.0/doc/build/doxygen/xml/index.xml
1484 WARNING:
1486 doxygentypedef: Cannot find file: /builddir/build/BUILD/libc‐
1487 bor-0.5.0/doc/build/doxygen/xml/index.xml
1488 WARNING:
1490 doxygentypedef: Cannot find file: /builddir/build/BUILD/libc‐
1491 bor-0.5.0/doc/build/doxygen/xml/index.xml
1492 Encoding
1494 TODO
1495 Tests
1497 Unit tests
1498 There is a comprehensive test suite employing CMocka. You can run all
1499 of them using ctest in the build directory. Individual tests are them‐
1500 selves runnable. Please refer to CTest documentation for detailed
1501 information on how to specify particular subset of tests.
1502 Testing for memory leaks
1504 Every release is tested for memory correctness. You can run these tests
1505 by passing the -T memcheck flag to ctest. [1]
1506 [1] Project should be configured with -DCMAKE_BUILD_TYPE=Debug to
1508 obtain meaningful description of location of the leak. You might
1509 also need --dsymutil=yes on OS X.
1510 Code coverage
1512 Every release is inspected using GCOV/LCOV. Platform-independent code
1513 should be fully covered by the test suite. Simply run
1514 make coverage
1516 or alternatively run lcov by hand using
1518 lcov --capture --directory . --output-file coverage.info
1520 genhtml coverage.info --output-directory out
1521 Fuzz testing
1523 Every release is tested using a fuzz test. In this test, a huge buffer
1524 filled with random data is passed to the decoder. We require that it
1525 either succeeds or fail with a sensible error, without leaking any mem‐
1526 ory. This is intended to simulate real-world situations where data
1527 received from the network are CBOR-decoded before any further process‐
1528 ing.
1529 RFC conformance
1531 libcbor is, generally speaking, very faithful implementation of RFC
1532 7049. There are, however, some limitations imposed by technical con‐
1533 straints.
1534 Bytestring length
1536 There is no explicit limitation of indefinite length byte strings. [1]
1537 libcbor will not handle byte strings with more chunks than the maximum
1538 value of size_t. On any sane platform, such string would not fit in the
1539 memory anyway. It is, however, possible to process arbitrarily long
1540 strings and byte strings using the streaming decoder.
1541 [1] http://tools.ietf.org/html/rfc7049#section-2.2.2
1543 Half-precision IEEE 754 floats
1545 As of C99 and even C11, there is no standard implementation for 2 bytes
1546 floats. libcbor packs them as a float. When encoding, libcbor selects
1547 the appropriate wire representation based on metadata and the actual
1548 value. This applies both to canonical and normal mode.
1549 For more information on half-float serialization, please refer to the
1551 section on api_type_7_hard_floats.
1552 Internal mechanics
1554 Internal workings of libcbor are mostly derived from the specification.
1555 The purpose of this document is to describe technical choices made dur‐
1556 ing design & implementation and to explicate the reasoning behind those
1557 choices.
1558 Terminology
1560 ┌────┬─────────────────────┬────────────────────────────────────────────────┐
1561 │MTB │ Major Type Byte │ http://tools.ietf.org/html/rfc7049#section-2.1 │
1562 ├────┼─────────────────────┼────────────────────────────────────────────────┤
1563 │DST │ Dynamically Sized │ Type whose storage requirements cannot be │
1564 │ │ Type │ determined │
1565 │ │ │ │
1566 │ │ │ during compilation (originated in the Rust │
1567 │ │ │ community) │
1568 └────┴─────────────────────┴────────────────────────────────────────────────┘
1569 Conventions
1571 API symbols start with cbor_ or CBOR_ prefix, internal symbols have
1572 _cbor_ or _CBOR_ prefix.
1573 Inspiration & related projects
1575 Most of the API is largely modelled after existing JSON libraries,
1576 including
1577 · Jansson
1579 · json-c
1581 · Gnome's JsonGlib
1583 and also borrowing from
1585 · msgpack-c
1587 · Google Protocol Buffers.
1589 General notes on the API design
1591 The API design has two main driving priciples:
1592 1. Let the client manage the memory as much as possible
1594 2. Behave exactly as specified by the standard
1596 Combining these two principles in practice turns out to be quite diffi‐
1598 cult. Indefinite-length strings, arrays, and maps require client to
1599 handle every fixed-size chunk explicitly in order to
1600 · ensure the client never runs out of memory due to libcbor
1602 · use realloc() sparsely and predictably [1]
1604 · provide strong guarantees about its usage (to prevent
1606 latency spikes)
1607 · provide APIs to avoid realloc() altogether
1609 · allow proper handling of (streamed) data bigger than available
1611 memory
1612 [1] Reasonable handling of DSTs requires reallocation if the API is
1614 to remain sane.
1615 Coding style
1617 This code loosely follows the Linux kernel coding style. Tabs are tabs,
1618 and they are 4 characters wide.
1619 Memory layout
1621 CBOR is very dynamic in the sense that it contains many data elements
1622 of variable length, sometimes even indefinite length. This section
1623 describes internal representation of all CBOR data types.
1624 Generally speaking, data items consist of three parts:
1626 · a generic handle,
1628 · the associated metadata,
1630 · and the actual data
1632 type cbor_item_t
1634 Represents the item. Used as an opaque type
1635 cbor_type type
1637 Type discriminator
1638 size_t refcount
1640 Reference counter. Used by cbor_decref(), cbor_incref()
1641 union cbor_item_metadata metadata
1643 Union discriminated by cbor_item_t.type. Contains
1644 type-specific metadata
1645 unsigned char *data
1647 Contains pointer to the actual data. Small, fixed size
1648 items (api/type_0_1, api/type_6, api/type_7) are allo‐
1649 cated as a single memory block.
1650 Consider the following snippet
1652 cbor_item_t * item = cbor_new_int8();
1654 then the memory is laid out as follows
1656 +-----------+---------------+---------------+-----------------------------------++-----------+
1658 | | | | || |
1659 | type | refcount | metadata | data || uint8_t |
1660 | | | | (= item + sizeof(cbor_item_t)) || |
1661 +-----------+---------------+---------------+-----------------------------------++-----------+
1662 ^ ^
1663 | |
1664 +--- item +--- item->data
1665 Dynamically sized types (api/type_2, api/type_3,
1667 api/type_4, api/type_5) may store handle and data in sep‐
1668 arate locations. This enables creating large items (e.g
1669 byte strings) without realloc() or copying large blocks
1670 of memory. One simply attaches the correct pointer to the
1671 handle.
1672 union cbor_item_metadata
1674 struct _cbor_int_metadata int_metadata;
1676 Used both by both api/type_0_1
1677 struct _cbor_bytestring_metadata bytestring_metadata;
1679 struct _cbor_string_metadata string_metadata;
1681 struct _cbor_array_metadata array_metadata;
1683 struct _cbor_map_metadata map_metadata;
1685 struct _cbor_tag_metadata tag_metadata;
1687 struct _cbor_float_ctrl_metadata float_ctrl_metadata;
1689 Decoding
1691 As outlined in api, there decoding is based on the streaming decoder
1692 Essentially, the decoder is a custom set of callbacks for the streaming
1693 decoder.
1694 Changelog
1696 Next
1697 0.5.0 (2017-02-06)
1698 · Remove cmocka from the subtree (always rely on system or user-pro‐
1699 vided version)
1700 · Windows CI
1702 · Only build tests if explicitly enabled (-DWITH_TESTS=ON)
1704 · Fixed static header declarations (by cedric-d)
1706 · Improved documentation (by Michael Richardson)
1708 · Improved examples/readfile.c
1710 · Reworked (re)allocation to handle huge inputs and overflows in size_t
1712 [#16]
1713 · Improvements to C++ linkage (corrected cbor_empty_callbacks, fixed
1715 restrict pointers) (by Dennis Bijwaard)
1716 · Fixed Linux installation directory depending on architecture [#34]
1718 (by jvymazal)
1719 · Improved 32-bit support [#35]
1721 · Fixed MSVC compatibility [#31]
1723 · Fixed and improved half-float encoding [#5] [#11]
1725 0.4.0 (2015-12-25)
1727 Breaks build & header compatibility due to:
1728 · Improved build configuration and feature check macros
1730 · Endianess configuration fixes (by Erwin Kroon and David Grigsby)
1732 · pkg-config compatibility (by Vincent Bernat)
1734 · enable use of versioned SONAME (by Vincent Bernat)
1736 · better fuzzer (wasn't random until now, ooops)
1738 0.3.1 (2015-05-21)
1740 · documentation and comments improvements, mostly for the API reference
1741 0.3.0 (2015-05-21)
1743 · Fixes, polishing, niceties across the code base
1744 · Updated examples
1746 · cbor_copy
1748 · cbor_build_negint8, 16, 32, 64, matching asserts
1750 · cbor_build_stringn
1752 · cbor_build_tag
1754 · cbor_build_float2, ...
1756 0.2.1 (2015-05-17)
1758 · C99 support
1759 0.2.0 (2015-05-17)
1761 · cbor_ctrl_bool -> cbor_ctrl_is_bool
1762 · Added cbor_array_allocated & map equivalent
1764 · Overhauled endianess conversion - ARM now works as expected
1766 · 'sort.c' example added
1768 · Significantly improved and doxyfied documentation
1770 0.1.0 (2015-05-06)
1772 The initial release, yay!
1773 Development
1775 Development dependencies
1776 · CMocka (testing)
1777 · Python and pip (Sphinx platform)
1779 · Doxygen
1781 · Sphinx (documentation)
1783 · There are some Ruby scripts in misc
1785 · Valgrind (memory correctness & profiling)
1787 · GCOV/LCOV (test coverage)
1789 Installing sphinx
1791 pip install sphinx
1792 pip install sphinx_rtd_theme
1793 pip install breathe
1794 pip install https://github.com/lepture/python-livereload/archive/master.zip
1795 pip install sphinx-autobuild
1796 Further instructions on configuring advanced features can be found at
1798 http://read-the-docs.readthedocs.org/en/latest/install.html.
1799 Live preview of docs
1801 cd doc
1802 make livehtml
1803 Set up git hooks
1805 A git hook that automatically refereshes the GH pages contents located
1806 in docs can be symlinked:
1807 ln -s misc/hooks/pre-commit .git/hooks
1809 Testing and code coverage
1811 Please refer to tests
1812
1814 Pavel Kalvoda
1815
1817 2014 - 2017, Pavel Kalvoda
18180.5 Feb 01, 2019 LIBCBOR(1)