1BSON_REFERENCE(3) libbson BSON_REFERENCE(3)
2
6 bson_reference - Index
7
9 A Cross Platform BSON Library for C
10 Introduction
12 libbson builds, parses, and iterates BSON documents, the native data
13 format of MongoDB. It also converts BSON to and from JSON, and provides
14 a platform compatibility layer for the MongoDB C Driver.
15 Tutorial
17 Using libbson In Your C Program
18 Include bson.h
19 All libbson's functions and types are available in one header file.
20 Simply include bson.h:
21 hello_bson.c
23 #include <stdio.h>
25 #include <bson/bson.h>
26 int
28 main (int argc, const char **argv)
29 {
30 bson_t *b;
31 char *j;
32 b = BCON_NEW ("hello", BCON_UTF8 ("bson!"));
34 j = bson_as_canonical_extended_json (b, NULL);
35 printf ("%s\n", j);
36 bson_free (j);
38 bson_destroy (b);
39 return 0;
41 }
42 CMake
45 The libbson installation includes a CMake config-file package, so you
46 can use CMake's find_package command to import libbson's CMake target
47 and link to libbson (as a shared library):
48 CMakeLists.txt
50 # Specify the minimum version you require.
52 find_package (bson-1.0 1.7 REQUIRED)
53 # The "hello_bson.c" sample program is shared among four tests.
55 add_executable (hello_bson ../../hello_bson.c)
56 target_link_libraries (hello_bson PRIVATE mongo::bson_shared)
57 You can also use libbson as a static library instead: Use the
60 mongo::bson_static CMake target:
61 # Specify the minimum version you require.
63 find_package (bson-1.0 1.7 REQUIRED)
64 # The "hello_bson.c" sample program is shared among four tests.
66 add_executable (hello_bson ../../hello_bson.c)
67 target_link_libraries (hello_bson PRIVATE mongo::bson_static)
68 pkg-config
71 If you're not using CMake, use pkg-config on the command line to set
72 header and library paths:
73 gcc -o hello_bson hello_bson.c $(pkg-config --libs --cflags libbson-1.0)
75 Or to statically link to libbson:
78 gcc -o hello_bson hello_bson.c $(pkg-config --libs --cflags libbson-static-1.0)
80 Creating a BSON Document
83 The bson_t structure
84 BSON documents are created using the bson_t structure. This structure
85 encapsulates the necessary logic for encoding using the BSON Specifica‐
86 tion. At the core, bson_t is a buffer manager and set of encoding rou‐
87 tines.
88 TIP:
90 BSON documents can live on the stack or the heap based on the per‐
91 formance needs or preference of the consumer.
92 Let's start by creating a new BSON document on the stack. Whenever us‐
94 ing libbson, make sure you #include <bson/bson.h>.
95 bson_t b;
97 bson_init (&b);
99 This creates an empty document. In JSON, this would be the same as {}.
101 We can now proceed to adding items to the BSON document. A variety of
103 functions prefixed with bson_append_ can be used based on the type of
104 field you want to append. Let's append a UTF-8 encoded string.
105 bson_append_utf8 (&b, "key", -1, "value", -1);
107 Notice the two -1 parameters. The first indicates that the length of
109 key in bytes should be determined with strlen(). Alternatively, we
110 could have passed the number 3. The same goes for the second -1, but
111 for value.
112 Libbson provides macros to make this less tedious when using string
114 literals. The following two appends are identical.
115 bson_append_utf8 (&b, "key", -1, "value", -1);
117 BSON_APPEND_UTF8 (&b, "key", "value");
118 Now let's take a look at an example that adds a few different field
120 types to a BSON document.
121 bson_t b = BSON_INITIALIZER;
123 BSON_APPEND_INT32 (&b, "a", 1);
125 BSON_APPEND_UTF8 (&b, "hello", "world");
126 BSON_APPEND_BOOL (&b, "bool", true);
127 Notice that we omitted the call to bson_init(). By specifying BSON_INI‐
129 TIALIZER we can remove the need to initialize the structure to a base
130 state.
131 Sub-Documents and Sub-Arrays
133 To simplify the creation of sub-documents and arrays, bson_append_docu‐
134 ment_begin() and bson_append_array_begin() exist. These can be used to
135 build a sub-document using the parent documents memory region as the
136 destination buffer.
137 bson_t parent;
139 bson_t child;
140 char *str;
141 bson_init (&parent);
143 bson_append_document_begin (&parent, "foo", 3, &child);
144 bson_append_int32 (&child, "baz", 3, 1);
145 bson_append_document_end (&parent, &child);
146 str = bson_as_canonical_extended_json (&parent, NULL);
148 printf ("%s\n", str);
149 bson_free (str);
150 bson_destroy (&parent);
152 { "foo" : { "baz" : 1 } }
154 Simplified BSON C Object Notation
156 Creating BSON documents by hand can be tedious and time consuming.
157 BCON, or BSON C Object Notation, was added to allow for the creation of
158 BSON documents in a format that looks closer to the destination format.
159 The following example shows the use of BCON. Notice that values for
161 fields are wrapped in the BCON_* macros. These are required for the
162 variadic processor to determine the parameter type.
163 bson_t *doc;
165 doc = BCON_NEW ("foo",
167 "{",
168 "int",
169 BCON_INT32 (1),
170 "array",
171 "[",
172 BCON_INT32 (100),
173 "{",
174 "sub",
175 BCON_UTF8 ("value"),
176 "}",
177 "]",
178 "}");
179 Creates the following document
181 { "foo" : { "int" : 1, "array" : [ 100, { "sub" : "value" } ] } }
183 Handling Errors
185 Description
186 Many libbson functions report errors by returning NULL or -1 and fill‐
187 ing out a bson_error_t structure with an error domain, error code, and
188 message.
189 • error.domain names the subsystem that generated the error.
191 • error.code is a domain-specific error type.
193 • error.message describes the error.
195 Some error codes overlap with others; always check both the domain and
197 code to determine the type of error.
198 ┌──────────────────┬─────────────────────┬────────────────────────────────┐
204 │BSON_ERROR_JSON │ BSON_JSON_ER‐ │ bson_json_reader_t │
205 │ │ ROR_READ_CORRUPT_JS │ tried to parse in‐ │
206 │ │ BSON_JSON_ER‐ │ valid MongoDB Ex‐ │
207 │ │ ROR_READ_IN‐ │ tended JSON. Tried │
208 │ │ VALID_PARAM │ to parse a valid │
209 │ │ BSON_JSON_ER‐ │ JSON document that │
210 │ │ ROR_READ_CB_FAILURE │ is invalid as Mon‐ │
211 │ │ │ goDBExtended JSON. │
212 │ │ │ An internal call‐ │
213 │ │ │ back failure during │
214 │ │ │ JSON parsing. │
215 ├──────────────────┼─────────────────────┼────────────────────────────────┤
216 │BSON_ERROR_READER │ BSON_ER‐ │ bson_json_reader_new_from_file │
217 │ │ ROR_READER_BADFD │ could not open the │
218 │ │ │ file. │
219 └──────────────────┴─────────────────────┴────────────────────────────────┘
220 ObjectIDs
222 Libbson provides a simple way to generate ObjectIDs. It can be used in
223 a single-threaded or multi-threaded manner depending on your require‐
224 ments.
225 The bson_oid_t structure represents an ObjectID in MongoDB. It is a
227 96-bit identifier.
228 Composition
230 • 4 bytes : The UNIX timestamp in big-endian format.
231 • 5 bytes : A random number.
233 • 3 bytes : A 24-bit monotonic counter incrementing from rand() in
235 big-endian.
236 Sorting ObjectIDs
238 The typical way to sort in C is using qsort(). Therefore, Libbson pro‐
239 vides a qsort() compatible callback function named bson_oid_compare().
240 It returns less than 1, greater than 1, or 0 depending on the equality
241 of two bson_oid_t structures.
242 Comparing Object IDs
244 If you simply want to compare two bson_oid_t structures for equality,
245 use bson_oid_equal().
246 Generating
248 To generate a bson_oid_t, you may use the following.
249 bson_oid_t oid;
251 bson_oid_init (&oid, NULL);
253 Parsing ObjectID Strings
255 You can also parse a string containing a bson_oid_t. The input string
256 MUST be 24 characters or more in length.
257 bson_oid_t oid;
259 bson_oid_init_from_string (&oid, "123456789012345678901234");
261 bson_oid_t oid;
263 bson_oid_init_from_string_unsafe (&oid, "123456789012345678901234");
265 Hashing ObjectIDs
267 If you need to store items in a hashtable, you may want to use the
268 bson_oid_t as the key. Libbson provides a hash function for just this
269 purpose. It is based on DJB hash.
270 unsigned hash;
272 hash = bson_oid_hash (oid);
274 Fetching ObjectID Creation Time
276 You can easily fetch the time that a bson_oid_t was generated using
277 bson_oid_get_time_t().
278 time_t t;
280 t = bson_oid_get_time_t (oid);
282 printf ("The OID was generated at %u\n", (unsigned) t);
283 Parsing and Iterating BSON Documents
285 Parsing
286 BSON documents are lazily parsed as necessary. To begin parsing a BSON
287 document, use one of the provided Libbson functions to create a new
288 bson_t from existing data such as bson_new_from_data(). This will make
289 a copy of the data so that additional mutations may occur to the BSON
290 document.
291 TIP:
293 If you only want to parse a BSON document and have no need to mutate
294 it, you may use bson_init_static() to avoid making a copy of the
295 data.
296 bson_t *b;
298 b = bson_new_from_data (my_data, my_data_len);
300 if (!b) {
301 fprintf (stderr, "The specified length embedded in <my_data> did not match "
302 "<my_data_len>\n");
303 return;
304 }
305 bson_destroy (b);
307 Only two checks are performed when creating a new bson_t from an exist‐
309 ing buffer. First, the document must begin with the buffer length,
310 matching what was expected by the caller. Second, the document must end
311 with the expected trailing \0 byte.
312 To parse the document further we use a bson_iter_t to iterate the ele‐
314 ments within the document. Let's print all of the field names in the
315 document.
316 bson_t *b;
318 bson_iter_t iter;
319 if ((b = bson_new_from_data (my_data, my_data_len))) {
321 if (bson_iter_init (&iter, b)) {
322 while (bson_iter_next (&iter)) {
323 printf ("Found element key: \"%s\"\n", bson_iter_key (&iter));
324 }
325 }
326 bson_destroy (b);
327 }
328 Converting a document to JSON uses a bson_iter_t and bson_visitor_t to
330 iterate all fields of a BSON document recursively and generate a UTF-8
331 encoded JSON string.
332 bson_t *b;
334 char *json;
335 if ((b = bson_new_from_data (my_data, my_data_len))) {
337 if ((json = bson_as_canonical_extended_json (b, NULL))) {
338 printf ("%s\n", json);
339 bson_free (json);
340 }
341 bson_destroy (b);
342 }
343 Recursing into Sub-Documents
345 Libbson provides convenient sub-iterators to dive down into a sub-docu‐
346 ment or sub-array. Below is an example that will dive into a sub-docu‐
347 ment named "foo" and print it's field names.
348 bson_iter_t iter;
350 bson_iter_t child;
351 char *json;
352 if (bson_iter_init_find (&iter, doc, "foo") &&
354 BSON_ITER_HOLDS_DOCUMENT (&iter) && bson_iter_recurse (&iter, &child)) {
355 while (bson_iter_next (&child)) {
356 printf ("Found sub-key of \"foo\" named \"%s\"\n",
357 bson_iter_key (&child));
358 }
359 }
360 Finding Fields using Dot Notation
362 Using the bson_iter_recurse() function exemplified above,
363 bson_iter_find_descendant() can find a field for you using the MongoDB
364 style path notation such as "foo.bar.0.baz".
365 Let's create a document like {"foo": {"bar": [{"baz: 1}]}} and locate
367 the "baz" field.
368 bson_t *b;
370 bson_iter_t iter;
371 bson_iter_t baz;
372 b =
374 BCON_NEW ("foo", "{", "bar", "[", "{", "baz", BCON_INT32 (1), "}", "]", "}");
375 if (bson_iter_init (&iter, b) &&
377 bson_iter_find_descendant (&iter, "foo.bar.0.baz", &baz) &&
378 BSON_ITER_HOLDS_INT32 (&baz)) {
379 printf ("baz = %d\n", bson_iter_int32 (&baz));
380 }
381 bson_destroy (b);
383 Validating a BSON Document
385 If all you want to do is validate that a BSON document is valid, you
386 can use bson_validate().
387 size_t err_offset;
389 if (!bson_validate (doc, BSON_VALIDATE_NONE, &err_offset)) {
391 fprintf (stderr,
392 "The document failed to validate at offset: %u\n",
393 (unsigned) err_offset);
394 }
395 See the bson_validate() documentation for more information and exam‐
397 ples.
398 UTF-8
400 Encoding
401 Libbson expects that you are always working with UTF-8 encoded text.
402 Anything else is invalid API use.
403 If you should need to walk through UTF-8 sequences, you can use the
405 various UTF-8 helper functions distributed with Libbson.
406 Validating a UTF-8 Sequence
408 To validate the string contained in my_string, use the following. You
409 may pass -1 for the string length if you know the string is NULL-termi‐
410 nated.
411 if (!bson_utf8_validate (my_string, -1, false)) {
413 printf ("Validation failed.\n");
414 }
415 If my_string has NULL bytes within the string, you must provide the
417 string length. Use the following format. Notice the true at the end in‐
418 dicating \0 is allowed.
419 if (!bson_utf8_validate (my_string, my_string_len, true)) {
421 printf ("Validation failed.\n");
422 }
423 For more information see the API reference for bson_utf8_validate().
425 Guides
427 Streaming BSON
428 bson_reader_t provides a streaming reader which can be initialized with
429 a filedescriptor or memory region. bson_writer_t provides a streaming
430 writer which can be initialized with a memory region. (Streaming BSON
431 to a file descriptor is not yet supported.)
432 Reading from a BSON Stream
434 bson_reader_t provides a convenient API to read sequential BSON docu‐
435 ments from a file-descriptor or memory buffer. The bson_reader_read()
436 function will read forward in the underlying stream and return a bson_t
437 that can be inspected and iterated upon.
438 #include <stdio.h>
440 #include <bson/bson.h>
441 int
443 main (int argc, char *argv[])
444 {
445 bson_reader_t *reader;
446 const bson_t *doc;
447 bson_error_t error;
448 bool eof;
449 reader = bson_reader_new_from_file ("mycollection.bson", &error);
451 if (!reader) {
453 fprintf (stderr, "Failed to open file.\n");
454 return 1;
455 }
456 while ((doc = bson_reader_read (reader, &eof))) {
458 char *str = bson_as_canonical_extended_json (doc, NULL);
459 printf ("%s\n", str);
460 bson_free (str);
461 }
462 if (!eof) {
464 fprintf (stderr,
465 "corrupted bson document found at %u\n",
466 (unsigned) bson_reader_tell (reader));
467 }
468 bson_reader_destroy (reader);
470 return 0;
472 }
473 See bson_reader_new_from_fd(), bson_reader_new_from_file(), and
475 bson_reader_new_from_data() for more information.
476 Writing a sequence of BSON Documents
478 bson_writer_t provides a convenient API to write a sequence of BSON
479 documents to a memory buffer that can grow with realloc(). The
480 bson_writer_begin() and bson_writer_end() functions will manage the un‐
481 derlying buffer while building the sequence of documents.
482 This could also be useful if you want to write to a network packet
484 while serializing the documents from a higher level language, (but do
485 so just after the packets header).
486 #include <stdio.h>
488 #include <bson/bson.h>
489 #include <assert.h>
490 int
492 main (int argc, char *argv[])
493 {
494 bson_writer_t *writer;
495 bson_t *doc;
496 uint8_t *buf = NULL;
497 size_t buflen = 0;
498 bool r;
499 int i;
500 writer = bson_writer_new (&buf, &buflen, 0, bson_realloc_ctx, NULL);
502 for (i = 0; i < 10000; i++) {
504 r = bson_writer_begin (writer, &doc);
505 assert (r);
506 r = BSON_APPEND_INT32 (doc, "i", i);
508 assert (r);
509 bson_writer_end (writer);
511 }
512 bson_free (buf);
514 return 0;
516 }
517 See bson_writer_new() for more information.
519 JSON
521 Libbson provides routines for converting to and from the JSON format.
522 In particular, it supports the MongoDB extended JSON format.
523 Converting BSON to JSON
525 There are often times where you might want to convert a BSON document
526 to JSON. It is convenient for debugging as well as an interchange for‐
527 mat. To help with this, Libbson contains the functions bson_as_canoni‐
528 cal_extended_json() and bson_as_relaxed_extended_json(). The canonical
529 format preserves BSON type information for values that may have ambigu‐
530 ous representations in JSON (e.g. numeric types).
531 bson_t *b;
533 size_t len;
534 char *str;
535 b = BCON_NEW ("a", BCON_INT32 (1));
537 str = bson_as_canonical_extended_json (b, &len);
539 printf ("%s\n", str);
540 bson_free (str);
541 bson_destroy (b);
543 { "a" : { "$numberInt": "1" } }
545 The relaxed format prefers JSON primitives for numeric values and may
547 be used if type fidelity is not required.
548 bson_t *b;
550 size_t len;
551 char *str;
552 b = BCON_NEW ("a", BCON_INT32 (1));
554 str = bson_as_relaxed_extended_json (b, &len);
556 printf ("%s\n", str);
557 bson_free (str);
558 bson_destroy (b);
560 { "a" : 1 }
562 Converting JSON to BSON
564 Converting back from JSON is also useful and common enough that we
565 added bson_init_from_json() and bson_new_from_json().
566 The following example creates a new bson_t from the JSON string
568 {"a":1}.
569 bson_t *b;
571 bson_error_t error;
572 b = bson_new_from_json ("{\"a\":1}", -1, &error);
574 if (!b) {
576 printf ("Error: %s\n", error.message);
577 } else {
578 bson_destroy (b);
579 }
580 Streaming JSON Parsing
582 Libbson provides bson_json_reader_t to allow for parsing a sequence of
583 JSON documents into BSON. The interface is similar to bson_reader_t but
584 expects the input to be in the MongoDB extended JSON format.
585 /*
587 * Copyright 2013 MongoDB, Inc.
588 *
589 * Licensed under the Apache License, Version 2.0 (the "License");
590 * you may not use this file except in compliance with the License.
591 * You may obtain a copy of the License at
592 *
593 * http://www.apache.org/licenses/LICENSE-2.0
594 *
595 * Unless required by applicable law or agreed to in writing, software
596 * distributed under the License is distributed on an "AS IS" BASIS,
597 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
598 * See the License for the specific language governing permissions and
599 * limitations under the License.
600 */
601 /*
604 * This program will print each JSON document contained in the provided files
605 * as a BSON string to STDOUT.
606 */
607 #include <bson/bson.h>
610 #include <stdlib.h>
611 #include <stdio.h>
612 int
615 main (int argc, char *argv[])
616 {
617 bson_json_reader_t *reader;
618 bson_error_t error;
619 const char *filename;
620 bson_t doc = BSON_INITIALIZER;
621 int i;
622 int b;
623 /*
625 * Print program usage if no arguments are provided.
626 */
627 if (argc == 1) {
628 fprintf (stderr, "usage: %s FILE...\n", argv[0]);
629 return 1;
630 }
631 /*
633 * Process command line arguments expecting each to be a filename.
634 */
635 for (i = 1; i < argc; i++) {
636 filename = argv[i];
637 /*
639 * Open the filename provided in command line arguments.
640 */
641 if (0 == strcmp (filename, "-")) {
642 reader = bson_json_reader_new_from_fd (STDIN_FILENO, false);
643 } else {
644 if (!(reader = bson_json_reader_new_from_file (filename, &error))) {
645 fprintf (
646 stderr, "Failed to open \"%s\": %s\n", filename, error.message);
647 continue;
648 }
649 }
650 /*
652 * Convert each incoming document to BSON and print to stdout.
653 */
654 while ((b = bson_json_reader_read (reader, &doc, &error))) {
655 if (b < 0) {
656 fprintf (stderr, "Error in json parsing:\n%s\n", error.message);
657 abort ();
658 }
659 if (fwrite (bson_get_data (&doc), 1, doc.len, stdout) != doc.len) {
661 fprintf (stderr, "Failed to write to stdout, exiting.\n");
662 exit (1);
663 }
664 bson_reinit (&doc);
665 }
666 bson_json_reader_destroy (reader);
668 bson_destroy (&doc);
669 }
670 return 0;
672 }
673 Examples
675 The following example reads BSON documents from stdin and prints them
676 to stdout as JSON.
677 /*
679 * Copyright 2013 MongoDB, Inc.
680 *
681 * Licensed under the Apache License, Version 2.0 (the "License");
682 * you may not use this file except in compliance with the License.
683 * You may obtain a copy of the License at
684 *
685 * http://www.apache.org/licenses/LICENSE-2.0
686 *
687 * Unless required by applicable law or agreed to in writing, software
688 * distributed under the License is distributed on an "AS IS" BASIS,
689 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
690 * See the License for the specific language governing permissions and
691 * limitations under the License.
692 */
693 /*
696 * This program will print each BSON document contained in the provided files
697 * as a JSON string to STDOUT.
698 */
699 #include <bson/bson.h>
702 #include <stdio.h>
703 int
706 main (int argc, char *argv[])
707 {
708 bson_reader_t *reader;
709 const bson_t *b;
710 bson_error_t error;
711 const char *filename;
712 char *str;
713 int i;
714 /*
716 * Print program usage if no arguments are provided.
717 */
718 if (argc == 1) {
719 fprintf (stderr, "usage: %s [FILE | -]...\nUse - for STDIN.\n", argv[0]);
720 return 1;
721 }
722 /*
724 * Process command line arguments expecting each to be a filename.
725 */
726 for (i = 1; i < argc; i++) {
727 filename = argv[i];
728 if (strcmp (filename, "-") == 0) {
730 reader = bson_reader_new_from_fd (STDIN_FILENO, false);
731 } else {
732 if (!(reader = bson_reader_new_from_file (filename, &error))) {
733 fprintf (
734 stderr, "Failed to open \"%s\": %s\n", filename, error.message);
735 continue;
736 }
737 }
738 /*
740 * Convert each incoming document to JSON and print to stdout.
741 */
742 while ((b = bson_reader_read (reader, NULL))) {
743 str = bson_as_canonical_extended_json (b, NULL);
744 fprintf (stdout, "%s\n", str);
745 bson_free (str);
746 }
747 /*
749 * Cleanup after our reader, which closes the file descriptor.
750 */
751 bson_reader_destroy (reader);
752 }
753 return 0;
755 }
756 Use Valgrind to Check For BSON Data Leaks
758 A stack-allocated bson_t contains a small internal buffer; it only
759 heap-allocates additional storage if necessary, depending on its data
760 size. Therefore if you forget to call bson_destroy on a stack-allocated
761 bson_t, it might or might not cause a leak that can be detected by val‐
762 grind during testing.
763 To catch all potential BSON data leaks in your code, configure the
765 BSON_MEMCHECK flag:
766 cmake -DCMAKE_C_FLAGS="-DBSON_MEMCHECK -g" .
768 With this flag set, every bson_t mallocs at least one byte. Run your
770 program's unittests with valgrind to verify all bson_t structs are de‐
771 stroyed.
772 Set the environment variable MONGOC_TEST_VALGRIND to on to skip tim‐
774 ing-dependent tests known to fail with valgrind.
775 Cross Platform Notes
777 Endianness
778 The BSON specification dictates that the encoding format is in lit‐
779 tle-endian. Many implementations simply ignore endianness altogether
780 and expect that they are to be run on little-endian. Libbson supports
781 both Big and Little Endian systems. This means we use memcpy() when ap‐
782 propriate instead of dereferencing and properly convert to and from the
783 host endian format. We expect the compiler intrinsics to optimize it to
784 a dereference when possible.
785 Threading
787 Libbson's data structures are NOT thread-safe. You are responsible for
788 accessing and mutating these structures from one thread at a time.
789 Libbson requires POSIX threads (pthreads) on all UNIX-like platforms.
791 On Windows, the native threading interface is used. Libbson uses your
792 system's threading library to safely generate unique ObjectIds, and to
793 provide a fallback implementation for atomic operations on platforms
794 without built-in atomics.
795 API Reference
797 bson_t
798 BSON Document Abstraction
799 Synopsis
801 #include <bson/bson.h>
802 /**
804 * bson_empty:
805 * @b: a bson_t.
806 *
807 * Checks to see if @b is an empty BSON document. An empty BSON document is
808 * a 5 byte document which contains the length (4 bytes) and a single NUL
809 * byte indicating end of fields.
810 */
811 #define bson_empty(b) /* ... */
812 /**
814 * bson_empty0:
815 *
816 * Like bson_empty() but treats NULL the same as an empty bson_t document.
817 */
818 #define bson_empty0(b) /* ... */
819 /**
821 * bson_clear:
822 *
823 * Easily free a bson document and set it to NULL. Use like:
824 *
825 * bson_t *doc = bson_new();
826 * bson_clear (&doc);
827 * BSON_ASSERT (doc == NULL);
828 */
829 #define bson_clear(bptr) /* ... */
830 /**
832 * BSON_MAX_SIZE:
833 *
834 * The maximum size in bytes of a BSON document.
835 */
836 #define BSON_MAX_SIZE /* ... */
837 #define BSON_APPEND_ARRAY(b, key, val) \
839 bson_append_array (b, key, (int) strlen (key), val)
840 #define BSON_APPEND_ARRAY_BEGIN(b, key, child) \
842 bson_append_array_begin (b, key, (int) strlen (key), child)
843 #define BSON_APPEND_BINARY(b, key, subtype, val, len) \
845 bson_append_binary (b, key, (int) strlen (key), subtype, val, len)
846 #define BSON_APPEND_BOOL(b, key, val) \
848 bson_append_bool (b, key, (int) strlen (key), val)
849 #define BSON_APPEND_CODE(b, key, val) \
851 bson_append_code (b, key, (int) strlen (key), val)
852 #define BSON_APPEND_CODE_WITH_SCOPE(b, key, val, scope) \
854 bson_append_code_with_scope (b, key, (int) strlen (key), val, scope)
855 #define BSON_APPEND_DBPOINTER(b, key, coll, oid) \
857 bson_append_dbpointer (b, key, (int) strlen (key), coll, oid)
858 #define BSON_APPEND_DOCUMENT_BEGIN(b, key, child) \
860 bson_append_document_begin (b, key, (int) strlen (key), child)
861 #define BSON_APPEND_DOUBLE(b, key, val) \
863 bson_append_double (b, key, (int) strlen (key), val)
864 #define BSON_APPEND_DOCUMENT(b, key, val) \
866 bson_append_document (b, key, (int) strlen (key), val)
867 #define BSON_APPEND_INT32(b, key, val) \
869 bson_append_int32 (b, key, (int) strlen (key), val)
870 #define BSON_APPEND_INT64(b, key, val) \
872 bson_append_int64 (b, key, (int) strlen (key), val)
873 #define BSON_APPEND_MINKEY(b, key) \
875 bson_append_minkey (b, key, (int) strlen (key))
876 #define BSON_APPEND_DECIMAL128(b, key, val) \
878 bson_append_decimal128 (b, key, (int) strlen (key), val)
879 #define BSON_APPEND_MAXKEY(b, key) \
881 bson_append_maxkey (b, key, (int) strlen (key))
882 #define BSON_APPEND_NULL(b, key) bson_append_null (b, key, (int) strlen (key))
884 #define BSON_APPEND_OID(b, key, val) \
886 bson_append_oid (b, key, (int) strlen (key), val)
887 #define BSON_APPEND_REGEX(b, key, val, opt) \
889 bson_append_regex (b, key, (int) strlen (key), val, opt)
890 #define BSON_APPEND_UTF8(b, key, val) \
892 bson_append_utf8 (b, key, (int) strlen (key), val, (int) strlen (val))
893 #define BSON_APPEND_SYMBOL(b, key, val) \
895 bson_append_symbol (b, key, (int) strlen (key), val, (int) strlen (val))
896 #define BSON_APPEND_TIME_T(b, key, val) \
898 bson_append_time_t (b, key, (int) strlen (key), val)
899 #define BSON_APPEND_TIMEVAL(b, key, val) \
901 bson_append_timeval (b, key, (int) strlen (key), val)
902 #define BSON_APPEND_DATE_TIME(b, key, val) \
904 bson_append_date_time (b, key, (int) strlen (key), val)
905 #define BSON_APPEND_TIMESTAMP(b, key, val, inc) \
907 bson_append_timestamp (b, key, (int) strlen (key), val, inc)
908 #define BSON_APPEND_UNDEFINED(b, key) \
910 bson_append_undefined (b, key, (int) strlen (key))
911 #define BSON_APPEND_VALUE(b, key, val) \
913 bson_append_value (b, key, (int) strlen (key), (val))
914 BSON_ALIGNED_BEGIN (128)
916 typedef struct {
917 uint32_t flags; /* Internal flags for the bson_t. */
918 uint32_t len; /* Length of BSON data. */
919 uint8_t padding[120]; /* Padding for stack allocation. */
920 } bson_t BSON_ALIGNED_END (128);
921 Description
923 The bson_t structure represents a BSON document. This structure manages
924 the underlying BSON encoded buffer. For mutable documents, it can ap‐
925 pend new data to the document.
926 Performance Notes
928 The bson_t structure attempts to use an inline allocation within the
929 structure to speed up performance of small documents. When this inter‐
930 nal buffer has been exhausted, a heap allocated buffer will be dynami‐
931 cally allocated. Therefore, it is essential to call bson_destroy() on
932 allocated documents.
933 Example
935 static void
936 create_on_heap (void)
937 {
938 bson_t *b = bson_new ();
939 BSON_APPEND_INT32 (b, "foo", 123);
941 BSON_APPEND_UTF8 (b, "bar", "foo");
942 BSON_APPEND_DOUBLE (b, "baz", 1.23f);
943 bson_destroy (b);
945 }
946 bson_context_t
948 BSON OID Generation Context
949 Synopsis
951 #include <bson/bson.h>
952 typedef enum {
954 BSON_CONTEXT_NONE = 0,
955 BSON_CONTEXT_DISABLE_PID_CACHE = (1 << 2),
956 } bson_context_flags_t;
957 typedef struct _bson_context_t bson_context_t;
959 bson_context_t *
961 bson_context_get_default (void) BSON_GNUC_CONST;
962 bson_context_t *
963 bson_context_new (bson_context_flags_t flags);
964 void
965 bson_context_destroy (bson_context_t *context);
966 Description
968 The bson_context_t structure is context for generation of BSON Object
969 IDs. This context allows overriding behavior of generating ObjectIDs.
970 The flags BSON_CONTEXT_NONE, BSON_CONTEXT_THREAD_SAFE, and BSON_CON‐
971 TEXT_DISABLE_PID_CACHE are the only ones used. The others have no ef‐
972 fect.
973 Example
975 #include <bson/bson.h>
976 int
978 main (int argc, char *argv[])
979 {
980 bson_context_t *ctx = NULL;
981 bson_oid_t oid;
982 /* use default context, via bson_context_get_default() */
984 bson_oid_init (&oid, NULL);
985 /* specify a local context for additional control */
987 ctx = bson_context_new (BSON_CONTEXT_NONE);
988 bson_oid_init (&oid, ctx);
989 bson_context_destroy (ctx);
991 return 0;
993 }
994 bson_decimal128_t
996 BSON Decimal128 Abstraction
997 Synopsis
999 #include <bson/bson.h>
1000 #define BSON_DECIMAL128_STRING 43
1002 #define BSON_DECIMAL128_INF "Infinity"
1003 #define BSON_DECIMAL128_NAN "NaN"
1004 typedef struct {
1006 #if BSON_BYTE_ORDER == BSON_LITTLE_ENDIAN
1007 uint64_t low;
1008 uint64_t high;
1009 #elif BSON_BYTE_ORDER == BSON_BIG_ENDIAN
1010 uint64_t high;
1011 uint64_t low;
1012 #endif
1013 } bson_decimal128_t;
1014 Description
1016 The bson_decimal128_t structure represents the IEEE-754 Decimal128 data
1017 type.
1018 Example
1020 #include <bson/bson.h>
1021 #include <stdio.h>
1022 int
1024 main (int argc, char *argv[])
1025 {
1026 char string[BSON_DECIMAL128_STRING];
1027 bson_decimal128_t decimal128;
1028 bson_decimal128_from_string ("100.00", &decimal128);
1030 bson_decimal128_to_string (&decimal128, string);
1031 printf ("Decimal128 value: %s\n", string);
1032 return 0;
1034 }
1035 bson_error_t
1037 BSON Error Encapsulation
1038 Synopsis
1040 #include <bson/bson.h>
1041 typedef struct {
1043 uint32_t domain;
1044 uint32_t code;
1045 char message[504];
1046 } bson_error_t;
1047 Description
1049 The bson_error_t structure is used as an out-parameter to pass error
1050 information to the caller. It should be stack-allocated and does not
1051 requiring freeing.
1052 See Handling Errors.
1054 Example
1056 bson_reader_t *reader;
1057 bson_error_t error;
1058 reader = bson_reader_new_from_file ("dump.bson", &error);
1060 if (!reader) {
1061 fprintf (
1062 stderr, "ERROR: %d.%d: %s\n", error.domain, error.code, error.message);
1063 }
1064 bson_iter_t
1066 BSON Document Iterator
1067 Synopsis
1069 #include <bson/bson.h>
1070 #define BSON_ITER_HOLDS_DOUBLE(iter) /* ... */
1072 #define BSON_ITER_HOLDS_UTF8(iter) /* ... */
1074 #define BSON_ITER_HOLDS_DOCUMENT(iter) /* ... */
1076 #define BSON_ITER_HOLDS_ARRAY(iter) /* ... */
1078 #define BSON_ITER_HOLDS_BINARY(iter) /* ... */
1080 #define BSON_ITER_HOLDS_UNDEFINED(iter) /* ... */
1082 #define BSON_ITER_HOLDS_OID(iter) /* ... */
1084 #define BSON_ITER_HOLDS_BOOL(iter) /* ... */
1086 #define BSON_ITER_HOLDS_DATE_TIME(iter) /* ... */
1088 #define BSON_ITER_HOLDS_NULL(iter) /* ... */
1090 #define BSON_ITER_HOLDS_REGEX(iter) /* ... */
1092 #define BSON_ITER_HOLDS_DBPOINTER(iter) /* ... */
1094 #define BSON_ITER_HOLDS_CODE(iter) /* ... */
1096 #define BSON_ITER_HOLDS_SYMBOL(iter) /* ... */
1098 #define BSON_ITER_HOLDS_CODEWSCOPE(iter) /* ... */
1100 #define BSON_ITER_HOLDS_INT32(iter) /* ... */
1102 #define BSON_ITER_HOLDS_TIMESTAMP(iter) /* ... */
1104 #define BSON_ITER_HOLDS_INT64(iter) /* ... */
1106 #define BSON_ITER_HOLDS_DECIMAL128(iter) /* ... */
1108 #define BSON_ITER_HOLDS_MAXKEY(iter) /* ... */
1110 #define BSON_ITER_HOLDS_MINKEY(iter) /* ... */
1112 #define BSON_ITER_HOLDS_INT(iter) \
1114 (BSON_ITER_HOLDS_INT32 (iter) || BSON_ITER_HOLDS_INT64 (iter))
1115 #define BSON_ITER_HOLDS_NUMBER(iter) \
1117 (BSON_ITER_HOLDS_INT (iter) || BSON_ITER_HOLDS_DOUBLE (iter))
1118 #define BSON_ITER_IS_KEY(iter, key) \
1120 (0 == strcmp ((key), bson_iter_key ((iter))))
1121 typedef struct {
1123 /*< private >*/
1124 } bson_iter_t;
1125 Description
1127 bson_iter_t is a structure used to iterate through the elements of a
1128 bson_t. It is meant to be used on the stack and can be discarded at any
1129 time as it contains no external allocation. The contents of the struc‐
1130 ture should be considered private and may change between releases, how‐
1131 ever the structure size will not change.
1132 The bson_t MUST be valid for the lifetime of the iter and it is an er‐
1134 ror to modify the bson_t while using the iter.
1135 Examples
1137 bson_iter_t iter;
1138 if (bson_iter_init (&iter, my_bson_doc)) {
1140 while (bson_iter_next (&iter)) {
1141 printf ("Found a field named: %s\n", bson_iter_key (&iter));
1142 }
1143 }
1144 bson_iter_t iter;
1146 if (bson_iter_init (&iter, my_bson_doc) && bson_iter_find (&iter, "my_field")) {
1148 printf ("Found the field named: %s\n", bson_iter_key (&iter));
1149 }
1150 bson_iter_t iter;
1152 bson_iter_t sub_iter;
1153 if (bson_iter_init_find (&iter, my_bson_doc, "mysubdoc") &&
1155 (BSON_ITER_HOLDS_DOCUMENT (&iter) || BSON_ITER_HOLDS_ARRAY (&iter)) &&
1156 bson_iter_recurse (&iter, &sub_iter)) {
1157 while (bson_iter_next (&sub_iter)) {
1158 printf ("Found key \"%s\" in sub document.\n", bson_iter_key (&sub_iter));
1159 }
1160 }
1161 bson_iter_t iter;
1163 if (bson_iter_init (&iter, my_doc) &&
1165 bson_iter_find_descendant (&iter, "a.b.c.d", &sub_iter)) {
1166 printf ("The type of a.b.c.d is: %d\n", (int) bson_iter_type (&sub_iter));
1167 }
1168 bson_json_reader_t
1170 Bulk JSON to BSON conversion
1171 Synopsis
1173 #include <bson/bson.h>
1174 typedef struct _bson_json_reader_t bson_json_reader_t;
1176 typedef enum {
1178 BSON_JSON_ERROR_READ_CORRUPT_JS = 1,
1179 BSON_JSON_ERROR_READ_INVALID_PARAM,
1180 BSON_JSON_ERROR_READ_CB_FAILURE,
1181 } bson_json_error_code_t;
1182 Description
1184 The bson_json_reader_t structure is used for reading a sequence of JSON
1185 documents and transforming them to bson_t documents.
1186 This can often be useful if you want to perform bulk operations that
1188 are defined in a file containing JSON documents.
1189 TIP:
1191 bson_json_reader_t works upon JSON documents formatted in MongoDB
1192 extended JSON format.
1193 Example
1195 /*
1196 * Copyright 2013 MongoDB, Inc.
1197 *
1198 * Licensed under the Apache License, Version 2.0 (the "License");
1199 * you may not use this file except in compliance with the License.
1200 * You may obtain a copy of the License at
1201 *
1202 * http://www.apache.org/licenses/LICENSE-2.0
1203 *
1204 * Unless required by applicable law or agreed to in writing, software
1205 * distributed under the License is distributed on an "AS IS" BASIS,
1206 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1207 * See the License for the specific language governing permissions and
1208 * limitations under the License.
1209 */
1210 /*
1213 * This program will print each JSON document contained in the provided files
1214 * as a BSON string to STDOUT.
1215 */
1216 #include <bson/bson.h>
1219 #include <stdlib.h>
1220 #include <stdio.h>
1221 int
1224 main (int argc, char *argv[])
1225 {
1226 bson_json_reader_t *reader;
1227 bson_error_t error;
1228 const char *filename;
1229 bson_t doc = BSON_INITIALIZER;
1230 int i;
1231 int b;
1232 /*
1234 * Print program usage if no arguments are provided.
1235 */
1236 if (argc == 1) {
1237 fprintf (stderr, "usage: %s FILE...\n", argv[0]);
1238 return 1;
1239 }
1240 /*
1242 * Process command line arguments expecting each to be a filename.
1243 */
1244 for (i = 1; i < argc; i++) {
1245 filename = argv[i];
1246 /*
1248 * Open the filename provided in command line arguments.
1249 */
1250 if (0 == strcmp (filename, "-")) {
1251 reader = bson_json_reader_new_from_fd (STDIN_FILENO, false);
1252 } else {
1253 if (!(reader = bson_json_reader_new_from_file (filename, &error))) {
1254 fprintf (
1255 stderr, "Failed to open \"%s\": %s\n", filename, error.message);
1256 continue;
1257 }
1258 }
1259 /*
1261 * Convert each incoming document to BSON and print to stdout.
1262 */
1263 while ((b = bson_json_reader_read (reader, &doc, &error))) {
1264 if (b < 0) {
1265 fprintf (stderr, "Error in json parsing:\n%s\n", error.message);
1266 abort ();
1267 }
1268 if (fwrite (bson_get_data (&doc), 1, doc.len, stdout) != doc.len) {
1270 fprintf (stderr, "Failed to write to stdout, exiting.\n");
1271 exit (1);
1272 }
1273 bson_reinit (&doc);
1274 }
1275 bson_json_reader_destroy (reader);
1277 bson_destroy (&doc);
1278 }
1279 return 0;
1281 }
1282 bson_md5_t
1284 BSON MD5 Abstraction
1285 Deprecated
1287 All MD5 APIs are deprecated in libbson.
1288 Synopsis
1290 typedef struct {
1291 uint32_t count[2]; /* message length in bits, lsw first */
1292 uint32_t abcd[4]; /* digest buffer */
1293 uint8_t buf[64]; /* accumulate block */
1294 } bson_md5_t;
1295 Description
1297 bson_md5_t encapsulates an implementation of the MD5 algorithm.
1298 bson_oid_t
1300 BSON ObjectID Abstraction
1301 Synopsis
1303 #include <bson/bson.h>
1304 typedef struct {
1306 uint8_t bytes[12];
1307 } bson_oid_t;
1308 Description
1310 The bson_oid_t structure contains the 12-byte ObjectId notation defined
1311 by the BSON ObjectID specification.
1312 ObjectId is a 12-byte BSON type, constructed using:
1314 • a 4-byte value representing the seconds since the Unix epoch (in Big
1316 Endian).
1317 • a 5-byte random value.
1319 • a 3-byte counter (Big Endian), starting with a random value.
1321 String Conversion
1323 You can convert an Object ID to a string using bson_oid_to_string() and
1324 back with bson_oid_init_from_string().
1325 Hashing
1327 A bson_oid_t can be used in hashtables using the function
1328 bson_oid_hash() and bson_oid_equal().
1329 Comparing
1331 A bson_oid_t can be compared to another using bson_oid_compare() for
1332 qsort() style comparing and bson_oid_equal() for direct equality.
1333 Validating
1335 You can validate that a string containing a hex-encoded ObjectID is
1336 valid using the function bson_oid_is_valid().
1337 Example
1339 #include <bson/bson.h>
1340 #include <stdio.h>
1341 int
1343 main (int argc, char *argv[])
1344 {
1345 bson_oid_t oid;
1346 char str[25];
1347 bson_oid_init (&oid, NULL);
1349 bson_oid_to_string (&oid, str);
1350 printf ("%s\n", str);
1351 if (bson_oid_is_valid (str, sizeof str)) {
1353 bson_oid_init_from_string (&oid, str);
1354 }
1355 printf ("The UNIX time was: %u\n", (unsigned) bson_oid_get_time_t (&oid));
1357 return 0;
1359 }
1360 bson_reader_t
1362 Streaming BSON Document Reader
1363 Synopsis
1365 #include <bson/bson.h>
1366 typedef struct _bson_reader_t bson_reader_t;
1368 bson_reader_t *
1370 bson_reader_new_from_handle (void *handle,
1371 bson_reader_read_func_t rf,
1372 bson_reader_destroy_func_t df);
1373 bson_reader_t *
1374 bson_reader_new_from_fd (int fd, bool close_on_destroy);
1375 bson_reader_t *
1376 bson_reader_new_from_file (const char *path, bson_error_t *error);
1377 bson_reader_t *
1378 bson_reader_new_from_data (const uint8_t *data, size_t length);
1379 void
1381 bson_reader_destroy (bson_reader_t *reader);
1382 Description
1384 bson_reader_t is a structure used for reading a sequence of BSON docu‐
1385 ments. The sequence can come from a file-descriptor, memory region, or
1386 custom callbacks.
1387 Example
1389 /*
1390 * Copyright 2013 MongoDB, Inc.
1391 *
1392 * Licensed under the Apache License, Version 2.0 (the "License");
1393 * you may not use this file except in compliance with the License.
1394 * You may obtain a copy of the License at
1395 *
1396 * http://www.apache.org/licenses/LICENSE-2.0
1397 *
1398 * Unless required by applicable law or agreed to in writing, software
1399 * distributed under the License is distributed on an "AS IS" BASIS,
1400 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1401 * See the License for the specific language governing permissions and
1402 * limitations under the License.
1403 */
1404 /*
1407 * This program will print each BSON document contained in the provided files
1408 * as a JSON string to STDOUT.
1409 */
1410 #include <bson/bson.h>
1413 #include <stdio.h>
1414 int
1417 main (int argc, char *argv[])
1418 {
1419 bson_reader_t *reader;
1420 const bson_t *b;
1421 bson_error_t error;
1422 const char *filename;
1423 char *str;
1424 int i;
1425 /*
1427 * Print program usage if no arguments are provided.
1428 */
1429 if (argc == 1) {
1430 fprintf (stderr, "usage: %s [FILE | -]...\nUse - for STDIN.\n", argv[0]);
1431 return 1;
1432 }
1433 /*
1435 * Process command line arguments expecting each to be a filename.
1436 */
1437 for (i = 1; i < argc; i++) {
1438 filename = argv[i];
1439 if (strcmp (filename, "-") == 0) {
1441 reader = bson_reader_new_from_fd (STDIN_FILENO, false);
1442 } else {
1443 if (!(reader = bson_reader_new_from_file (filename, &error))) {
1444 fprintf (
1445 stderr, "Failed to open \"%s\": %s\n", filename, error.message);
1446 continue;
1447 }
1448 }
1449 /*
1451 * Convert each incoming document to JSON and print to stdout.
1452 */
1453 while ((b = bson_reader_read (reader, NULL))) {
1454 str = bson_as_canonical_extended_json (b, NULL);
1455 fprintf (stdout, "%s\n", str);
1456 bson_free (str);
1457 }
1458 /*
1460 * Cleanup after our reader, which closes the file descriptor.
1461 */
1462 bson_reader_destroy (reader);
1463 }
1464 return 0;
1466 }
1467 Character and String Routines
1469 We provide a small number of character and string routines to substi‐
1470 tute for those that are not available on all platforms, and routines to
1471 make UTF-8 character manipulation convenient.
1472 bson_string_t
1474 String Building Abstraction
1475 Synopsis
1477 #include <bson/bson.h>
1478 typedef struct {
1480 char *str;
1481 uint32_t len;
1482 uint32_t alloc;
1483 } bson_string_t;
1484 Description
1486 bson_string_t is an abstraction for building strings. As chunks are
1487 added to the string, allocations are performed in powers of two.
1488 This API is useful if you need to build UTF-8 encoded strings.
1490 Example
1492 bson_string_t *str;
1493 str = bson_string_new (NULL);
1495 bson_string_append_printf (str, "%d %s %f\n", 0, "some string", 0.123);
1496 printf ("%s\n", str->str);
1497 bson_string_free (str, true);
1499 TIP:
1501 You can call bson_string_free() with false if you would like to take
1502 ownership of str->str. Some APIs that do this might call return
1503 bson_string_free (str, false); after building the string.
1504 bson_subtype_t
1506 Binary Field Subtype
1507 Synopsis
1509 #include <bson/bson.h>
1510 typedef enum {
1513 BSON_SUBTYPE_BINARY = 0x00,
1514 BSON_SUBTYPE_FUNCTION = 0x01,
1515 BSON_SUBTYPE_BINARY_DEPRECATED = 0x02,
1516 BSON_SUBTYPE_UUID_DEPRECATED = 0x03,
1517 BSON_SUBTYPE_UUID = 0x04,
1518 BSON_SUBTYPE_MD5 = 0x05,
1519 BSON_SUBTYPE_COLUMN = 0x07,
1520 BSON_SUBTYPE_USER = 0x80,
1521 } bson_subtype_t;
1522 Description
1524 This enumeration contains the various subtypes that may be used in a
1525 binary field. See http://bsonspec.org for more information.
1526 Example
1528 bson_t doc = BSON_INITIALIZER;
1529 BSON_APPEND_BINARY (&doc, "binary", BSON_SUBTYPE_BINARY, data, data_len);
1531 bson_type_t
1533 BSON Type Enumeration
1534 Synopsis
1536 #include <bson/bson.h>
1537 typedef enum {
1539 BSON_TYPE_EOD = 0x00,
1540 BSON_TYPE_DOUBLE = 0x01,
1541 BSON_TYPE_UTF8 = 0x02,
1542 BSON_TYPE_DOCUMENT = 0x03,
1543 BSON_TYPE_ARRAY = 0x04,
1544 BSON_TYPE_BINARY = 0x05,
1545 BSON_TYPE_UNDEFINED = 0x06,
1546 BSON_TYPE_OID = 0x07,
1547 BSON_TYPE_BOOL = 0x08,
1548 BSON_TYPE_DATE_TIME = 0x09,
1549 BSON_TYPE_NULL = 0x0A,
1550 BSON_TYPE_REGEX = 0x0B,
1551 BSON_TYPE_DBPOINTER = 0x0C,
1552 BSON_TYPE_CODE = 0x0D,
1553 BSON_TYPE_SYMBOL = 0x0E,
1554 BSON_TYPE_CODEWSCOPE = 0x0F,
1555 BSON_TYPE_INT32 = 0x10,
1556 BSON_TYPE_TIMESTAMP = 0x11,
1557 BSON_TYPE_INT64 = 0x12,
1558 BSON_TYPE_DECIMAL128 = 0x13,
1559 BSON_TYPE_MAXKEY = 0x7F,
1560 BSON_TYPE_MINKEY = 0xFF,
1561 } bson_type_t;
1562 Description
1564 The bson_type_t enumeration contains all of the types from the BSON
1565 Specification. It can be used to determine the type of a field at run‐
1566 time.
1567 Example
1569 bson_iter_t iter;
1570 if (bson_iter_init_find (&iter, doc, "foo") &&
1572 (BSON_TYPE_INT32 == bson_iter_type (&iter))) {
1573 printf ("'foo' is an int32.\n");
1574 }
1575 bson_unichar_t
1577 Unicode Character Abstraction
1578 Synopsis
1580 typedef uint32_t bson_unichar_t;
1581 Description
1583 bson_unichar_t provides an abstraction on a single unicode character.
1584 It is the 32-bit representation of a character. As UTF-8 can contain
1585 multi-byte characters, this should be used when iterating through UTF-8
1586 text.
1587 Example
1589 static void
1590 print_each_char (const char *str)
1591 {
1592 bson_unichar_t c;
1593 for (; *str; str = bson_utf8_next_char (str)) {
1595 c = bson_utf8_get_char (str);
1596 printf ("The numberic value is %u.\n", (unsigned) c);
1597 }
1598 }
1599 bson_value_t
1601 BSON Boxed Container Type
1602 Synopsis
1604 #include <bson/bson.h>
1605 typedef struct _bson_value_t {
1607 bson_type_t value_type;
1608 union {
1609 bson_oid_t v_oid;
1610 int64_t v_int64;
1611 int32_t v_int32;
1612 int8_t v_int8;
1613 double v_double;
1614 bool v_bool;
1615 int64_t v_datetime;
1616 struct {
1617 uint32_t timestamp;
1618 uint32_t increment;
1619 } v_timestamp;
1620 struct {
1621 uint32_t len;
1622 char *str;
1623 } v_utf8;
1624 struct {
1625 uint32_t data_len;
1626 uint8_t *data;
1627 } v_doc;
1628 struct {
1629 uint32_t data_len;
1630 uint8_t *data;
1631 bson_subtype_t subtype;
1632 } v_binary;
1633 struct {
1634 char *regex;
1635 char *options;
1636 } v_regex;
1637 struct {
1638 char *collection;
1639 uint32_t collection_len;
1640 bson_oid_t oid;
1641 } v_dbpointer;
1642 struct {
1643 uint32_t code_len;
1644 char *code;
1645 } v_code;
1646 struct {
1647 uint32_t code_len;
1648 char *code;
1649 uint32_t scope_len;
1650 uint8_t *scope_data;
1651 } v_codewscope;
1652 struct {
1653 uint32_t len;
1654 char *symbol;
1655 } v_symbol;
1656 } value;
1657 } bson_value_t;
1658 Description
1660 The bson_value_t structure is a boxed type for encapsulating a runtime
1661 determined type.
1662 Example
1664 const bson_value_t *value;
1665 value = bson_iter_value (&iter);
1667 if (value->value_type == BSON_TYPE_INT32) {
1669 printf ("%d\n", value->value.v_int32);
1670 }
1671 bson_visitor_t
1673 Synopsis
1674 #include <bson/bson.h>
1675 typedef struct {
1677 /* run before / after descending into a document */
1678 bool (*visit_before) (const bson_iter_t *iter, const char *key, void *data);
1679 bool (*visit_after) (const bson_iter_t *iter, const char *key, void *data);
1680 /* corrupt BSON, or unsupported type and visit_unsupported_type not set */
1681 void (*visit_corrupt) (const bson_iter_t *iter, void *data);
1682 /* normal bson field callbacks */
1683 bool (*visit_double) (const bson_iter_t *iter,
1684 const char *key,
1685 double v_double,
1686 void *data);
1687 bool (*visit_utf8) (const bson_iter_t *iter,
1688 const char *key,
1689 size_t v_utf8_len,
1690 const char *v_utf8,
1691 void *data);
1692 bool (*visit_document) (const bson_iter_t *iter,
1693 const char *key,
1694 const bson_t *v_document,
1695 void *data);
1696 bool (*visit_array) (const bson_iter_t *iter,
1697 const char *key,
1698 const bson_t *v_array,
1699 void *data);
1700 bool (*visit_binary) (const bson_iter_t *iter,
1701 const char *key,
1702 bson_subtype_t v_subtype,
1703 size_t v_binary_len,
1704 const uint8_t *v_binary,
1705 void *data);
1706 /* normal field with deprecated "Undefined" BSON type */
1707 bool (*visit_undefined) (const bson_iter_t *iter,
1708 const char *key,
1709 void *data);
1710 bool (*visit_oid) (const bson_iter_t *iter,
1711 const char *key,
1712 const bson_oid_t *v_oid,
1713 void *data);
1714 bool (*visit_bool) (const bson_iter_t *iter,
1715 const char *key,
1716 bool v_bool,
1717 void *data);
1718 bool (*visit_date_time) (const bson_iter_t *iter,
1719 const char *key,
1720 int64_t msec_since_epoch,
1721 void *data);
1722 bool (*visit_null) (const bson_iter_t *iter, const char *key, void *data);
1723 bool (*visit_regex) (const bson_iter_t *iter,
1724 const char *key,
1725 const char *v_regex,
1726 const char *v_options,
1727 void *data);
1728 bool (*visit_dbpointer) (const bson_iter_t *iter,
1729 const char *key,
1730 size_t v_collection_len,
1731 const char *v_collection,
1732 const bson_oid_t *v_oid,
1733 void *data);
1734 bool (*visit_code) (const bson_iter_t *iter,
1735 const char *key,
1736 size_t v_code_len,
1737 const char *v_code,
1738 void *data);
1739 bool (*visit_symbol) (const bson_iter_t *iter,
1740 const char *key,
1741 size_t v_symbol_len,
1742 const char *v_symbol,
1743 void *data);
1744 bool (*visit_codewscope) (const bson_iter_t *iter,
1745 const char *key,
1746 size_t v_code_len,
1747 const char *v_code,
1748 const bson_t *v_scope,
1749 void *data);
1750 bool (*visit_int32) (const bson_iter_t *iter,
1751 const char *key,
1752 int32_t v_int32,
1753 void *data);
1754 bool (*visit_timestamp) (const bson_iter_t *iter,
1755 const char *key,
1756 uint32_t v_timestamp,
1757 uint32_t v_increment,
1758 void *data);
1759 bool (*visit_int64) (const bson_iter_t *iter,
1760 const char *key,
1761 int64_t v_int64,
1762 void *data);
1763 bool (*visit_maxkey) (const bson_iter_t *iter, const char *key, void *data);
1764 bool (*visit_minkey) (const bson_iter_t *iter, const char *key, void *data);
1765 /* if set, called instead of visit_corrupt when an apparently valid BSON
1766 * includes an unrecognized field type (reading future version of BSON) */
1767 void (*visit_unsupported_type) (const bson_iter_t *iter,
1768 const char *key,
1769 uint32_t type_code,
1770 void *data);
1771 bool (*visit_decimal128) (const bson_iter_t *iter,
1772 const char *key,
1773 const bson_decimal128_t *v_decimal128,
1774 void *data);
1775 void *padding[7];
1777 } bson_visitor_t bson_visitor_t;
1778 Description
1780 The bson_visitor_t structure provides a series of callbacks that can be
1781 called while iterating a BSON document. This may simplify the conver‐
1782 sion of a bson_t to a higher level language structure.
1783 If the optional callback visit_unsupported_type is set, it is called
1785 instead of visit_corrupt in the specific case of an unrecognized field
1786 type. (Parsing is aborted in either case.) Use this callback to report
1787 an error like "unrecognized type" instead of simply "corrupt BSON".
1788 This future-proofs code that may use an older version of libbson to
1789 parse future BSON formats.
1790 Basic Example
1792 #include <bson/bson.h>
1793 #include <stdio.h>
1794 static bool
1796 my_visit_before (const bson_iter_t *iter, const char *key, void *data)
1797 {
1798 int *count = (int *) data;
1799 (*count)++;
1801 /* returning true stops further iteration of the document */
1803 return false;
1805 }
1806 static void
1808 count_fields (bson_t *doc)
1809 {
1810 bson_visitor_t visitor = {0};
1811 bson_iter_t iter;
1812 int count = 0;
1813 visitor.visit_before = my_visit_before;
1815 if (bson_iter_init (&iter, doc)) {
1817 bson_iter_visit_all (&iter, &visitor, &count);
1818 }
1819 printf ("Found %d fields.\n", count);
1821 }
1822 The example below demonstrates how to set your own callbacks to provide
1824 information about the location of corrupt or unsupported BSON document
1825 entries.
1826 Example Corruption Check
1828 #include <bson/bson.h>
1829 #include <stdio.h>
1830 typedef struct {
1832 ssize_t *err_offset;
1833 } my_state_t;
1834 static void
1836 my_visit_corrupt (const bson_iter_t *iter, void *data)
1837 {
1838 *(((my_state_t *) data)->err_offset) = iter->off;
1839 }
1840 static void
1842 my_visit_unsupported_type (const bson_iter_t *iter,
1843 const char *key,
1844 uint32_t type_code,
1845 void *data)
1846 {
1847 *(((my_state_t *) data)->err_offset) = iter->off;
1848 }
1849 static void
1851 find_error_location (bson_t *doc)
1852 {
1853 bson_visitor_t visitors = {0};
1854 bson_iter_t iter;
1855 my_state_t state;
1856 ssize_t err_offset = -1;
1857 visitors.visit_corrupt = my_visit_corrupt;
1859 visitors.visit_unsupported_type = my_visit_unsupported_type;
1860 /* provide additional visitors as needed based on your requirements */
1861 state.err_offset = &err_offset;
1862 if (!bson_iter_init (&iter, doc)) {
1864 printf ("Could not initialize iterator!");
1865 exit (1);
1866 }
1867 if (bson_iter_visit_all (&iter, &visitors, &state) ||
1869 err_offset != -1) {
1870 printf ("Found error at offset %d.\n", err_offset);
1871 } else {
1872 printf ("BSON document had no errors.\n");
1873 }
1874 }
1875 The example below demonstrates how to use a visitor to validate a BSON
1877 document's maximum depth.
1878 Example Custom Validation
1880 bson-check-depth.c
1881 /* Reports the maximum nested depth of a BSON document. */
1883 #include <bson/bson.h>
1884 #include <assert.h>
1886 #include <stdio.h>
1887 #include <stdlib.h>
1888 typedef struct {
1890 uint32_t depth;
1891 int max_depth;
1892 bool valid;
1893 } check_depth_t;
1894 bool
1896 _check_depth_document (const bson_iter_t *iter,
1897 const char *key,
1898 const bson_t *v_document,
1899 void *data);
1900 static const bson_visitor_t check_depth_funcs = {
1902 NULL,
1903 NULL,
1904 NULL,
1905 NULL,
1906 NULL,
1907 _check_depth_document,
1908 _check_depth_document,
1909 NULL,
1910 };
1911 bool
1913 _check_depth_document (const bson_iter_t *iter,
1914 const char *key,
1915 const bson_t *v_document,
1916 void *data)
1917 {
1918 check_depth_t *state = (check_depth_t *) data;
1919 bson_iter_t child;
1920 if (!bson_iter_init (&child, v_document)) {
1922 fprintf (stderr, "corrupt\n");
1923 return true; /* cancel */
1924 }
1925 state->depth++;
1927 if (state->depth > state->max_depth) {
1928 state->valid = false;
1929 return true; /* cancel */
1930 }
1931 bson_iter_visit_all (&child, &check_depth_funcs, state);
1933 state->depth--;
1934 return false; /* continue */
1935 }
1936 void
1938 check_depth (const bson_t *bson, int max_depth)
1939 {
1940 bson_iter_t iter;
1941 check_depth_t state = {0};
1942 if (!bson_iter_init (&iter, bson)) {
1944 fprintf (stderr, "corrupt\n");
1945 }
1946 state.valid = true;
1948 state.max_depth = max_depth;
1949 _check_depth_document (&iter, NULL, bson, &state);
1950 if (!state.valid) {
1951 printf ("document exceeds maximum depth of %d\n", state.max_depth);
1952 } else {
1953 char *as_json = bson_as_canonical_extended_json (bson, NULL);
1954 printf ("document %s ", as_json);
1955 printf ("is valid\n");
1956 bson_free (as_json);
1957 }
1958 }
1959 int
1961 main (int argc, char **argv)
1962 {
1963 bson_reader_t *bson_reader;
1964 const bson_t *bson;
1965 bool reached_eof;
1966 char *filename;
1967 bson_error_t error;
1968 int max_depth;
1969 if (argc != 3) {
1971 fprintf (stderr, "usage: %s FILE MAX_DEPTH\n", argv[0]);
1972 fprintf (stderr, "Checks that the depth of the BSON contained in FILE\n");
1973 fprintf (stderr, "does not exceed MAX_DEPTH\n");
1974 }
1975 filename = argv[1];
1977 max_depth = atoi (argv[2]);
1978 bson_reader = bson_reader_new_from_file (filename, &error);
1979 if (!bson_reader) {
1980 printf ("could not read %s: %s\n", filename, error.message);
1981 return 1;
1982 }
1983 while ((bson = bson_reader_read (bson_reader, &reached_eof))) {
1985 check_depth (bson, max_depth);
1986 }
1987 if (!reached_eof) {
1989 printf ("error reading BSON\n");
1990 }
1991 bson_reader_destroy (bson_reader);
1993 return 0;
1994 }
1995 bson_writer_t
1998 Bulk BSON serialization Abstraction
1999 Synopsis
2001 #include <bson/bson.h>
2002 typedef struct _bson_writer_t bson_writer_t;
2004 bson_writer_t *
2006 bson_writer_new (uint8_t **buf,
2007 size_t *buflen,
2008 size_t offset,
2009 bson_realloc_func realloc_func,
2010 void *realloc_func_ctx);
2011 void
2012 bson_writer_destroy (bson_writer_t *writer);
2013 Description
2015 The bson_writer_t API provides an abstraction for serializing many BSON
2016 documents to a single memory region. The memory region may be dynami‐
2017 cally allocated and re-allocated as more memory is demanded. This can
2018 be useful when building network packets from a high-level language. For
2019 example, you can serialize a Python Dictionary directly to a single
2020 buffer destined for a TCP packet.
2021 Example
2023 #include <bson/bson.h>
2024 int
2026 main (int argc, char *argv[])
2027 {
2028 bson_writer_t *writer;
2029 uint8_t *buf = NULL;
2030 size_t buflen = 0;
2031 bson_t *doc;
2032 writer = bson_writer_new (&buf, &buflen, 0, bson_realloc_ctx, NULL);
2034 for (i = 0; i < 1000; i++) {
2036 bson_writer_begin (writer, &doc);
2037 BSON_APPEND_INT32 (&doc, "i", i);
2038 bson_writer_end (writer);
2039 }
2040 bson_writer_destroy (writer);
2042 bson_free (buf);
2044 return 0;
2046 }
2047 System Clock
2049 BSON Clock Abstraction
2050 Synopsis
2052 int64_t
2053 bson_get_monotonic_time (void);
2054 int
2055 bson_gettimeofday (struct timeval *tv);
2056 Description
2058 The clock abstraction in Libbson provides a cross-platform way to han‐
2059 dle timeouts within the BSON library. It abstracts the differences in
2060 implementations of gettimeofday() as well as providing a monotonic (in‐
2061 crementing only) clock in microseconds.
2062 Memory Management
2064 BSON Memory Abstraction.
2065 Description
2067 Libbson contains a lightweight memory abstraction to make portability
2068 to new platforms easier. Additionally, it helps us integrate with in‐
2069 teresting higher-level languages. One caveat, however, is that Libbson
2070 is not designed to deal with Out of Memory (OOM) situations. Doing so
2071 requires extreme diligence throughout the application stack that has
2072 rarely been implemented correctly. This may change in the future. As it
2073 stands now, Libbson will abort() under OOM situations.
2074 To aid in language binding integration, Libbson allows for setting a
2076 custom memory allocator via bson_mem_set_vtable(). This allocation may
2077 be reversed via bson_mem_restore_vtable().
2078 Libbson Versioning
2080 Versioning Macros and Functions
2081 Macros
2083 The following preprocessor macros can be used to perform various checks
2084 based on the version of the library you are compiling against. This may
2085 be useful if you only want to enable a feature on a certain version of
2086 the library.
2087 Synopsis
2089 #define BSON_CHECK_VERSION(major, minor, micro)
2090 #define BSON_MAJOR_VERSION (1)
2092 #define BSON_MINOR_VERSION (4)
2093 #define BSON_MICRO_VERSION (1)
2094 #define BSON_VERSION_S "1.4.1"
2095 #define BSON_VERSION_HEX \
2097 (BSON_MAJOR_VERSION << 24 | BSON_MINOR_VERSION << 16 | \
2098 BSON_MICRO_VERSION << 8)
2099 Only compile a block on Libbson 1.1.0 and newer.
2101 #if BSON_CHECK_VERSION(1, 1, 0)
2103 static void
2104 do_something (void)
2105 {
2106 }
2107 #endif
2108
2110 MongoDB, Inc
2111
2113 2017-present, MongoDB, Inc
21141.21.1 Mar 02, 2022 BSON_REFERENCE(3)