README.md
1# [libcbor](https://github.com/PJK/libcbor)
2
3[](https://circleci.com/gh/PJK/libcbor/tree/master)
4[](https://readthedocs.org/projects/libcbor/?badge=latest)
5[](https://repology.org/project/libcbor/versions)
6[](https://codecov.io/gh/PJK/libcbor)
7
8**libcbor** is a C library for parsing and generating [CBOR](https://cbor.io/), the general-purpose schema-less binary data format.
9
10## Main features
11 - Complete [IETF RFC 8949 (STD 94)](https://www.rfc-editor.org/info/std94) conformance
12 - Robust platform-independent C99 implementation
13 - Layered architecture offers both control and convenience
14 - Flexible memory management
15 - No shared global state - threading friendly
16 - Proper handling of UTF-8
17 - Full support for streams & incremental processing
18 - Extensive documentation and test suite
19 - No runtime dependencies, small footprint
20
21## Getting started
22
23### Compile from source
24
25```bash
26git clone https://github.com/PJK/libcbor
27cmake -DCMAKE_BUILD_TYPE=Release libcbor
28make
29make install
30```
31
32### Homebrew
33
34```bash
35brew install libcbor
36```
37
38### Ubuntu 18.04 and above
39
40```bash
41sudo add-apt-repository universe
42sudo apt-get install libcbor-dev
43```
44
45### Fedora & RPM friends
46
47```bash
48yum install libcbor-devel
49```
50
51### Others
52
53<details>
54 <summary>Packaged libcbor is available from 15+ major repositories. Click here for more detail</summary>
55
56 [](https://repology.org/project/libcbor/versions)
57</details>
58
59## Usage example
60
61```c
62#include <cbor.h>
63#include <stdio.h>
64
65int main(void) {
66 /* Preallocate the map structure */
67 cbor_item_t* root = cbor_new_definite_map(2);
68 /* Add the content */
69 bool success = cbor_map_add(
70 root, (struct cbor_pair){
71 .key = cbor_move(cbor_build_string("Is CBOR awesome?")),
72 .value = cbor_move(cbor_build_bool(true))});
73 success &= cbor_map_add(
74 root, (struct cbor_pair){
75 .key = cbor_move(cbor_build_uint8(42)),
76 .value = cbor_move(cbor_build_string("Is the answer"))});
77 if (!success) return 1;
78 /* Output: `length` bytes of data in the `buffer` */
79 unsigned char* buffer;
80 size_t buffer_size;
81 cbor_serialize_alloc(root, &buffer, &buffer_size);
82
83 fwrite(buffer, 1, buffer_size, stdout);
84 free(buffer);
85
86 fflush(stdout);
87 cbor_decref(&root);
88}
89```
90
91## Documentation
92Get the latest documentation at [libcbor.readthedocs.org](http://libcbor.readthedocs.org/)
93
94## Contributions
95
96Bug reports and contributions are welcome. Please see [CONTRIBUTING.md](https://github.com/PJK/libcbor/blob/master/CONTRIBUTING.md) for more info.
97
98Kudos to all the [contributors](https://github.com/PJK/libcbor/graphs/contributors)!
99
100## License
101The MIT License (MIT)
102
103Copyright (c) Pavel Kalvoda, 2014-2020
104
105Permission is hereby granted, free of charge, to any person obtaining a copy
106of this software and associated documentation files (the "Software"), to deal
107in the Software without restriction, including without limitation the rights
108to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
109copies of the Software, and to permit persons to whom the Software is
110furnished to do so, subject to the following conditions:
111
112The above copyright notice and this permission notice shall be included in all
113copies or substantial portions of the Software.
114
115THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
116IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
117FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
118AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
119LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
120OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
121SOFTWARE.
122
