FreeBSD Manual Pages
BSON_REFERENCE(3) libbson BSON_REFERENCE(3) LIBBSON - API A Cross Platform BSON Library for C This site documents the API. For tutorials, guides, and explainers, see MongoDB C Driver. Introduction libbson builds, parses, and iterates BSON documents, the native data format of MongoDB. It also converts BSON to and from JSON, and provides a platform compatibility layer for the MongoDB C Driver. API Reference bson_t BSON Document Abstraction Synopsis #include <bson/bson.h> /** * bson_empty: * @b: a bson_t. * * Checks to see if @b is an empty BSON document. An empty BSON document is * a 5 byte document which contains the length (4 bytes) and a single NUL * byte indicating end of fields. */ #define bson_empty(b) /* ... */ /** * bson_empty0: * * Like bson_empty() but treats NULL the same as an empty bson_t document. */ #define bson_empty0(b) /* ... */ /** * bson_clear: * * Easily free a bson document and set it to NULL. Use like: * * bson_t *doc = bson_new(); * bson_clear (&doc); * BSON_ASSERT (doc == NULL); */ #define bson_clear(bptr) /* ... */ /** * BSON_MAX_SIZE: * * The maximum size in bytes of a BSON document. */ #define BSON_MAX_SIZE /* ... */ #define BSON_APPEND_ARRAY(b, key, val) \ bson_append_array (b, key, (int) strlen (key), val) #define BSON_APPEND_ARRAY_BEGIN(b, key, child) \ bson_append_array_begin (b, key, (int) strlen (key), child) #define BSON_APPEND_BINARY(b, key, subtype, val, len) \ bson_append_binary (b, key, (int) strlen (key), subtype, val, len) #define BSON_APPEND_BOOL(b, key, val) \ bson_append_bool (b, key, (int) strlen (key), val) #define BSON_APPEND_CODE(b, key, val) \ bson_append_code (b, key, (int) strlen (key), val) #define BSON_APPEND_CODE_WITH_SCOPE(b, key, val, scope) \ bson_append_code_with_scope (b, key, (int) strlen (key), val, scope) #define BSON_APPEND_DBPOINTER(b, key, coll, oid) \ bson_append_dbpointer (b, key, (int) strlen (key), coll, oid) #define BSON_APPEND_DOCUMENT_BEGIN(b, key, child) \ bson_append_document_begin (b, key, (int) strlen (key), child) #define BSON_APPEND_DOUBLE(b, key, val) \ bson_append_double (b, key, (int) strlen (key), val) #define BSON_APPEND_DOCUMENT(b, key, val) \ bson_append_document (b, key, (int) strlen (key), val) #define BSON_APPEND_INT32(b, key, val) \ bson_append_int32 (b, key, (int) strlen (key), val) #define BSON_APPEND_INT64(b, key, val) \ bson_append_int64 (b, key, (int) strlen (key), val) #define BSON_APPEND_MINKEY(b, key) \ bson_append_minkey (b, key, (int) strlen (key)) #define BSON_APPEND_DECIMAL128(b, key, val) \ bson_append_decimal128 (b, key, (int) strlen (key), val) #define BSON_APPEND_MAXKEY(b, key) \ bson_append_maxkey (b, key, (int) strlen (key)) #define BSON_APPEND_NULL(b, key) bson_append_null (b, key, (int) strlen (key)) #define BSON_APPEND_OID(b, key, val) \ bson_append_oid (b, key, (int) strlen (key), val) #define BSON_APPEND_REGEX(b, key, val, opt) \ bson_append_regex (b, key, (int) strlen (key), val, opt) #define BSON_APPEND_UTF8(b, key, val) \ bson_append_utf8 (b, key, (int) strlen (key), val, (int) strlen (val)) #define BSON_APPEND_SYMBOL(b, key, val) \ bson_append_symbol (b, key, (int) strlen (key), val, (int) strlen (val)) #define BSON_APPEND_TIME_T(b, key, val) \ bson_append_time_t (b, key, (int) strlen (key), val) #define BSON_APPEND_TIMEVAL(b, key, val) \ bson_append_timeval (b, key, (int) strlen (key), val) #define BSON_APPEND_DATE_TIME(b, key, val) \ bson_append_date_time (b, key, (int) strlen (key), val) #define BSON_APPEND_TIMESTAMP(b, key, val, inc) \ bson_append_timestamp (b, key, (int) strlen (key), val, inc) #define BSON_APPEND_UNDEFINED(b, key) \ bson_append_undefined (b, key, (int) strlen (key)) #define BSON_APPEND_VALUE(b, key, val) \ bson_append_value (b, key, (int) strlen (key), (val)) BSON_ALIGNED_BEGIN (128) typedef struct { uint32_t flags; /* Internal flags for the bson_t. */ uint32_t len; /* Length of BSON data. */ uint8_t padding[120]; /* Padding for stack allocation. */ } bson_t BSON_ALIGNED_END (128); Description The bson_t structure represents a BSON document. This structure manages the underlying BSON encoded buffer. For mutable documents, it can ap- pend new data to the document. Performance Notes The bson_t structure attempts to use an inline allocation within the structure to speed up performance of small documents. When this inter- nal buffer has been exhausted, a heap allocated buffer will be dynami- cally allocated. Therefore, it is essential to call bson_destroy() on allocated documents. Duplicate Keys The BSON specification allows BSON documents to have duplicate keys. Documents are stored as an ordered list of key-value pairs. A bson_t may contain duplicate keys. Applications should refrain from generating such documents, because MongoDB server behavior is undefined when a BSON document contains duplicate keys. Example static void create_on_heap (void) { bson_t *b = bson_new (); BSON_APPEND_INT32 (b, "foo", 123); BSON_APPEND_UTF8 (b, "bar", "foo"); BSON_APPEND_DOUBLE (b, "baz", 1.23f); bson_destroy (b); } bson_array_builder_t typedef struct _bson_array_builder_t bson_array_builder_t; bson_array_builder_t may be used to build BSON arrays. bson_ar- ray_builder_t internally tracks and uses the array index as a key ("0", "1", "2", ...) when appending elements. Appending an array value typedef struct _bson_array_builder_t bson_array_builder_t; bool bson_append_array_builder_begin (bson_t *bson, const char *key, int key_length, bson_array_builder_t **child); bool bson_append_array_builder_end (bson_t *bson, bson_array_builder_t *child); #define BSON_APPEND_ARRAY_BUILDER_BEGIN(b, key, child) \ bson_append_array_builder_begin (b, key, (int) strlen (key), child) bson_append_array_builder_begin may be used to append an array as a value. Example: bson_t parent = BSON_INITIALIZER; bson_array_builder_t *bab; bson_append_array_builder_begin (&parent, "foo", 3, &bab); bson_array_builder_append_int32 (bab, 9); bson_array_builder_append_int32 (bab, 8); bson_array_builder_append_int32 (bab, 7); bson_append_array_builder_end (&parent, bab); char *str = bson_as_relaxed_extended_json (&parent, NULL); printf ("%s\n", str); // Prints: { "foo" : [ 9, 8, 7 ] } bson_free (str); bson_destroy (&parent); Creating a top-level array bson_array_builder_t * bson_array_builder_new (void); bool bson_array_builder_build (bson_array_builder_t *bab, bson_t *out); void bson_array_builder_destroy (bson_array_builder_t *bab); bson_array_builder_new and bson_array_builder_build may be used to build a top-level BSON array. bson_array_builder_build initializes and moves BSON data to out. The bson_array_builder_t may be reused and will start appending a new array at index "0": Example: bson_t out; bson_array_builder_t *bab = bson_array_builder_new (); bson_array_builder_append_int32 (bab, 9); bson_array_builder_append_int32 (bab, 8); bson_array_builder_append_int32 (bab, 7); bson_array_builder_build (bab, &out); char *str = bson_array_as_relaxed_extended_json (&out, NULL); printf ("%s\n", str); // Prints: [ 9, 8, 7 ] bson_free (str); bson_array_builder_destroy (bab); Appending values to an array bson_array_builder_append_* functions are provided to append values to a BSON array. The bson_array_builder_append_* functions internally use bson_append_* and provide the array index as a key: bool bson_array_builder_append_value (bson_array_builder_t *bab, const bson_value_t *value); bool bson_array_builder_append_array (bson_array_builder_t *bab, const bson_t *array); bool bson_array_builder_append_binary (bson_array_builder_t *bab, bson_subtype_t subtype, const uint8_t *binary, uint32_t length); bool bson_array_builder_append_bool (bson_array_builder_t *bab, bool value); bool bson_array_builder_append_code (bson_array_builder_t *bab, const char *javascript); bool bson_array_builder_append_code_with_scope (bson_array_builder_t *bab, const char *javascript, const bson_t *scope); bool bson_array_builder_append_dbpointer (bson_array_builder_t *bab, const char *collection, const bson_oid_t *oid); bool bson_array_builder_append_double (bson_array_builder_t *bab, double value); bool bson_array_builder_append_document (bson_array_builder_t *bab, const bson_t *value); bool bson_array_builder_append_document_begin (bson_array_builder_t *bab, bson_t *child); bool bson_array_builder_append_document_end (bson_array_builder_t *bab, bson_t *child); bool bson_array_builder_append_int32 (bson_array_builder_t *bab, int32_t value); bool bson_array_builder_append_int64 (bson_array_builder_t *bab, int64_t value); bool bson_array_builder_append_decimal128 (bson_array_builder_t *bab, const bson_decimal128_t *value); bool bson_array_builder_append_iter (bson_array_builder_t *bab, const bson_iter_t *iter); bool bson_array_builder_append_minkey (bson_array_builder_t *bab); bool bson_array_builder_append_maxkey (bson_array_builder_t *bab); bool bson_array_builder_append_null (bson_array_builder_t *bab); bool bson_array_builder_append_oid (bson_array_builder_t *bab, const bson_oid_t *oid); bool bson_array_builder_append_regex (bson_array_builder_t *bab, const char *regex, const char *options); bool bson_array_builder_append_regex_w_len (bson_array_builder_t *bab, const char *regex, int regex_length, const char *options); bool bson_array_builder_append_utf8 (bson_array_builder_t *bab, const char *value, int length); bool bson_array_builder_append_symbol (bson_array_builder_t *bab, const char *value, int length); bool bson_array_builder_append_time_t (bson_array_builder_t *bab, time_t value); bool bson_array_builder_append_timeval (bson_array_builder_t *bab, struct timeval *value); bool bson_array_builder_append_date_time (bson_array_builder_t *bab, int64_t value); bool bson_array_builder_append_now_utc (bson_array_builder_t *bab); bool bson_array_builder_append_timestamp (bson_array_builder_t *bab, uint32_t timestamp, uint32_t increment); bool bson_array_builder_append_undefined (bson_array_builder_t *bab); bool bson_array_builder_append_array_builder_begin (bson_array_builder_t *bab, bson_array_builder_t **child); bool bson_array_builder_append_array_builder_end (bson_array_builder_t *bab, bson_array_builder_t *child); bson_context_t BSON OID Generation Context Synopsis #include <bson/bson.h> typedef enum { BSON_CONTEXT_NONE = 0, BSON_CONTEXT_DISABLE_PID_CACHE = (1 << 2), } bson_context_flags_t; typedef struct _bson_context_t bson_context_t; bson_context_t * bson_context_get_default (void); bson_context_t * bson_context_new (bson_context_flags_t flags); void bson_context_destroy (bson_context_t *context); Description The bson_context_t structure is context for generation of BSON Object IDs. This context allows overriding behavior of generating ObjectIDs. The flags BSON_CONTEXT_NONE, BSON_CONTEXT_THREAD_SAFE, and BSON_CON- TEXT_DISABLE_PID_CACHE are the only ones used. The others have no ef- fect. Example #include <bson/bson.h> int main (int argc, char *argv[]) { bson_context_t *ctx = NULL; bson_oid_t oid; /* use default context, via bson_context_get_default() */ bson_oid_init (&oid, NULL); /* specify a local context for additional control */ ctx = bson_context_new (BSON_CONTEXT_NONE); bson_oid_init (&oid, ctx); bson_context_destroy (ctx); return 0; } bson_decimal128_t BSON Decimal128 Abstraction Synopsis #include <bson/bson.h> #define BSON_DECIMAL128_STRING 43 #define BSON_DECIMAL128_INF "Infinity" #define BSON_DECIMAL128_NAN "NaN" typedef struct { #if BSON_BYTE_ORDER == BSON_LITTLE_ENDIAN uint64_t low; uint64_t high; #elif BSON_BYTE_ORDER == BSON_BIG_ENDIAN uint64_t high; uint64_t low; #endif } bson_decimal128_t; Description The bson_decimal128_t structure represents the IEEE-754 Decimal128 data type. The type bson_decimal128_t is an aggregate that contains two uint64_ts, named high and low. The declaration and layout order between them depends on the endian order of the target platform: low will al- ways correspond to the low-order bits of the Decimal128 object, while high corresponds to the high-order bits. The bson_decimal128_t always has a size of sixteen (16), and can be bit-cast to/from a _Decimal128. Example #include <bson/bson.h> #include <stdio.h> int main (int argc, char *argv[]) { char string[BSON_DECIMAL128_STRING]; bson_decimal128_t decimal128; bson_decimal128_from_string ("100.00", &decimal128); bson_decimal128_to_string (&decimal128, string); printf ("Decimal128 value: %s\n", string); return 0; } bson_error_t BSON Error Encapsulation Synopsis #include <bson/bson.h> typedef struct { uint32_t domain; uint32_t code; char message[504]; } bson_error_t; Description The bson_error_t structure is used as an out-parameter to pass error information to the caller. It should be stack-allocated and does not requiring freeing. See Handling Errors. Example bson_reader_t *reader; bson_error_t error; reader = bson_reader_new_from_file ("dump.bson", &error); if (!reader) { fprintf ( stderr, "ERROR: %d.%d: %s\n", error.domain, error.code, error.message); } bson_iter_t BSON Document Iterator Synopsis #include <bson/bson.h> #define BSON_ITER_HOLDS_DOUBLE(iter) /* ... */ #define BSON_ITER_HOLDS_UTF8(iter) /* ... */ #define BSON_ITER_HOLDS_DOCUMENT(iter) /* ... */ #define BSON_ITER_HOLDS_ARRAY(iter) /* ... */ #define BSON_ITER_HOLDS_BINARY(iter) /* ... */ #define BSON_ITER_HOLDS_UNDEFINED(iter) /* ... */ #define BSON_ITER_HOLDS_OID(iter) /* ... */ #define BSON_ITER_HOLDS_BOOL(iter) /* ... */ #define BSON_ITER_HOLDS_DATE_TIME(iter) /* ... */ #define BSON_ITER_HOLDS_NULL(iter) /* ... */ #define BSON_ITER_HOLDS_REGEX(iter) /* ... */ #define BSON_ITER_HOLDS_DBPOINTER(iter) /* ... */ #define BSON_ITER_HOLDS_CODE(iter) /* ... */ #define BSON_ITER_HOLDS_SYMBOL(iter) /* ... */ #define BSON_ITER_HOLDS_CODEWSCOPE(iter) /* ... */ #define BSON_ITER_HOLDS_INT32(iter) /* ... */ #define BSON_ITER_HOLDS_TIMESTAMP(iter) /* ... */ #define BSON_ITER_HOLDS_INT64(iter) /* ... */ #define BSON_ITER_HOLDS_DECIMAL128(iter) /* ... */ #define BSON_ITER_HOLDS_MAXKEY(iter) /* ... */ #define BSON_ITER_HOLDS_MINKEY(iter) /* ... */ #define BSON_ITER_HOLDS_INT(iter) \ (BSON_ITER_HOLDS_INT32 (iter) || BSON_ITER_HOLDS_INT64 (iter)) #define BSON_ITER_HOLDS_NUMBER(iter) \ (BSON_ITER_HOLDS_INT (iter) || BSON_ITER_HOLDS_DOUBLE (iter)) #define BSON_ITER_IS_KEY(iter, key) \ (0 == strcmp ((key), bson_iter_key ((iter)))) typedef struct { /*< private >*/ } bson_iter_t; Description bson_iter_t is a structure used to iterate through the elements of a bson_t. It is meant to be used on the stack and can be discarded at any time as it contains no external allocation. The contents of the struc- ture should be considered private and may change between releases, how- ever the structure size will not change. The bson_t MUST be valid for the lifetime of the iter and it is an er- ror to modify the bson_t while using the iter. Examples bson_iter_t iter; if (bson_iter_init (&iter, my_bson_doc)) { while (bson_iter_next (&iter)) { printf ("Found a field named: %s\n", bson_iter_key (&iter)); } } bson_iter_t iter; if (bson_iter_init (&iter, my_bson_doc) && bson_iter_find (&iter, "my_field")) { printf ("Found the field named: %s\n", bson_iter_key (&iter)); } bson_iter_t iter; bson_iter_t sub_iter; if (bson_iter_init_find (&iter, my_bson_doc, "mysubdoc") && (BSON_ITER_HOLDS_DOCUMENT (&iter) || BSON_ITER_HOLDS_ARRAY (&iter)) && bson_iter_recurse (&iter, &sub_iter)) { while (bson_iter_next (&sub_iter)) { printf ("Found key \"%s\" in sub document.\n", bson_iter_key (&sub_iter)); } } bson_iter_t iter; if (bson_iter_init (&iter, my_doc) && bson_iter_find_descendant (&iter, "a.b.c.d", &sub_iter)) { printf ("The type of a.b.c.d is: %d\n", (int) bson_iter_type (&sub_iter)); } bson_json_reader_t Bulk JSON to BSON conversion Synopsis #include <bson/bson.h> typedef struct _bson_json_reader_t bson_json_reader_t; typedef enum { BSON_JSON_ERROR_READ_CORRUPT_JS = 1, BSON_JSON_ERROR_READ_INVALID_PARAM, BSON_JSON_ERROR_READ_CB_FAILURE, } bson_json_error_code_t; Description The bson_json_reader_t structure is used for reading a sequence of JSON documents and transforming them to bson_t documents. This can often be useful if you want to perform bulk operations that are defined in a file containing JSON documents. TIP: bson_json_reader_t works upon JSON documents formatted in MongoDB extended JSON format. Example /* * Copyright 2009-present MongoDB, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /* * This program will print each JSON document contained in the provided files * as a BSON string to STDOUT. */ #include <bson/bson.h> #include <stdlib.h> #include <stdio.h> int main (int argc, char *argv[]) { bson_json_reader_t *reader; bson_error_t error; const char *filename; bson_t doc = BSON_INITIALIZER; int i; int b; /* * Print program usage if no arguments are provided. */ if (argc == 1) { fprintf (stderr, "usage: %s FILE...\n", argv[0]); return 1; } /* * Process command line arguments expecting each to be a filename. */ for (i = 1; i < argc; i++) { filename = argv[i]; /* * Open the filename provided in command line arguments. */ if (0 == strcmp (filename, "-")) { reader = bson_json_reader_new_from_fd (STDIN_FILENO, false); } else { if (!(reader = bson_json_reader_new_from_file (filename, &error))) { fprintf ( stderr, "Failed to open \"%s\": %s\n", filename, error.message); continue; } } /* * Convert each incoming document to BSON and print to stdout. */ while ((b = bson_json_reader_read (reader, &doc, &error))) { if (b < 0) { fprintf (stderr, "Error in json parsing:\n%s\n", error.message); abort (); } if (fwrite (bson_get_data (&doc), 1, doc.len, stdout) != doc.len) { fprintf (stderr, "Failed to write to stdout, exiting.\n"); exit (1); } bson_reinit (&doc); } bson_json_reader_destroy (reader); bson_destroy (&doc); } return 0; } bson_oid_t BSON ObjectID Abstraction Synopsis #include <bson/bson.h> typedef struct { uint8_t bytes[12]; } bson_oid_t; Description The bson_oid_t structure contains the 12-byte ObjectId notation defined by the BSON ObjectID specification. ObjectId is a 12-byte BSON type, constructed using: • a 4-byte value representing the seconds since the Unix epoch (in Big Endian). • a 5-byte random value. • a 3-byte counter (Big Endian), starting with a random value. String Conversion You can convert an Object ID to a string using bson_oid_to_string() and back with bson_oid_init_from_string(). Hashing A bson_oid_t can be used in hashtables using the function bson_oid_hash() and bson_oid_equal(). Comparing A bson_oid_t can be compared to another using bson_oid_compare() for qsort() style comparing and bson_oid_equal() for direct equality. Validating You can validate that a string containing a hex-encoded ObjectID is valid using the function bson_oid_is_valid(). Example #include <bson/bson.h> #include <stdio.h> int main (int argc, char *argv[]) { bson_oid_t oid; char str[25]; bson_oid_init (&oid, NULL); bson_oid_to_string (&oid, str); printf ("%s\n", str); if (bson_oid_is_valid (str, sizeof str)) { bson_oid_init_from_string (&oid, str); } printf ("The UNIX time was: %u\n", (unsigned) bson_oid_get_time_t (&oid)); return 0; } bson_reader_t Streaming BSON Document Reader Synopsis #include <bson/bson.h> typedef struct _bson_reader_t bson_reader_t; bson_reader_t * bson_reader_new_from_handle (void *handle, bson_reader_read_func_t rf, bson_reader_destroy_func_t df); bson_reader_t * bson_reader_new_from_fd (int fd, bool close_on_destroy); bson_reader_t * bson_reader_new_from_file (const char *path, bson_error_t *error); bson_reader_t * bson_reader_new_from_data (const uint8_t *data, size_t length); void bson_reader_destroy (bson_reader_t *reader); Description bson_reader_t is a structure used for reading a sequence of BSON docu- ments. The sequence can come from a file-descriptor, memory region, or custom callbacks. Example /* * Copyright 2009-present MongoDB, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /* * This program will print each BSON document contained in the provided files * as a JSON string to STDOUT. */ #include <bson/bson.h> #include <stdio.h> int main (int argc, char *argv[]) { bson_reader_t *reader; const bson_t *b; bson_error_t error; const char *filename; char *str; int i; /* * Print program usage if no arguments are provided. */ if (argc == 1) { fprintf (stderr, "usage: %s [FILE | -]...\nUse - for STDIN.\n", argv[0]); return 1; } /* * Process command line arguments expecting each to be a filename. */ for (i = 1; i < argc; i++) { filename = argv[i]; if (strcmp (filename, "-") == 0) { reader = bson_reader_new_from_fd (STDIN_FILENO, false); } else { if (!(reader = bson_reader_new_from_file (filename, &error))) { fprintf ( stderr, "Failed to open \"%s\": %s\n", filename, error.message); continue; } } /* * Convert each incoming document to JSON and print to stdout. */ while ((b = bson_reader_read (reader, NULL))) { str = bson_as_canonical_extended_json (b, NULL); fprintf (stdout, "%s\n", str); bson_free (str); } /* * Cleanup after our reader, which closes the file descriptor. */ bson_reader_destroy (reader); } return 0; } Character and String Routines We provide a small number of character and string routines to substi- tute for those that are not available on all platforms, and routines to make UTF-8 character manipulation convenient. bson_string_t WARNING: Deprecated since version 1.29.0. String Building Abstraction Synopsis #include <bson/bson.h> typedef struct { char *str; uint32_t len; uint32_t alloc; } bson_string_t; Description bson_string_t is an abstraction for building strings. As chunks are added to the string, allocations are performed in powers of two. This API is useful if you need to build UTF-8 encoded strings. Example bson_string_t *str; str = bson_string_new (NULL); bson_string_append_printf (str, "%d %s %f\n", 0, "some string", 0.123); printf ("%s\n", str->str); bson_string_free (str, true); TIP: You can call bson_string_free() with false if you would like to take ownership of str->str. Some APIs that do this might call return bson_string_free (str, false); after building the string. bson_subtype_t Binary Field Subtype Synopsis #include <bson/bson.h> typedef enum { BSON_SUBTYPE_BINARY = 0x00, BSON_SUBTYPE_FUNCTION = 0x01, BSON_SUBTYPE_BINARY_DEPRECATED = 0x02, BSON_SUBTYPE_UUID_DEPRECATED = 0x03, BSON_SUBTYPE_UUID = 0x04, BSON_SUBTYPE_MD5 = 0x05, BSON_SUBTYPE_COLUMN = 0x07, BSON_SUBTYPE_SENSITIVE = 0x08, BSON_SUBTYPE_USER = 0x80, } bson_subtype_t; Description This enumeration contains the various subtypes that may be used in a binary field. See http://bsonspec.org for more information. Example bson_t doc = BSON_INITIALIZER; BSON_APPEND_BINARY (&doc, "binary", BSON_SUBTYPE_BINARY, data, data_len); bson_type_t BSON Type Enumeration Synopsis #include <bson/bson.h> typedef enum { BSON_TYPE_EOD = 0x00, BSON_TYPE_DOUBLE = 0x01, BSON_TYPE_UTF8 = 0x02, BSON_TYPE_DOCUMENT = 0x03, BSON_TYPE_ARRAY = 0x04, BSON_TYPE_BINARY = 0x05, BSON_TYPE_UNDEFINED = 0x06, BSON_TYPE_OID = 0x07, BSON_TYPE_BOOL = 0x08, BSON_TYPE_DATE_TIME = 0x09, BSON_TYPE_NULL = 0x0A, BSON_TYPE_REGEX = 0x0B, BSON_TYPE_DBPOINTER = 0x0C, BSON_TYPE_CODE = 0x0D, BSON_TYPE_SYMBOL = 0x0E, BSON_TYPE_CODEWSCOPE = 0x0F, BSON_TYPE_INT32 = 0x10, BSON_TYPE_TIMESTAMP = 0x11, BSON_TYPE_INT64 = 0x12, BSON_TYPE_DECIMAL128 = 0x13, BSON_TYPE_MAXKEY = 0x7F, BSON_TYPE_MINKEY = 0xFF, } bson_type_t; Description The bson_type_t enumeration contains all of the types from the BSON Specification. It can be used to determine the type of a field at run- time. Example bson_iter_t iter; if (bson_iter_init_find (&iter, doc, "foo") && (BSON_TYPE_INT32 == bson_iter_type (&iter))) { printf ("'foo' is an int32.\n"); } bson_unichar_t Unicode Character Abstraction Synopsis typedef uint32_t bson_unichar_t; Description bson_unichar_t provides an abstraction on a single unicode character. It is the 32-bit representation of a character. As UTF-8 can contain multi-byte characters, this should be used when iterating through UTF-8 text. Example static void print_each_char (const char *str) { bson_unichar_t c; for (; *str; str = bson_utf8_next_char (str)) { c = bson_utf8_get_char (str); printf ("The numberic value is %u.\n", (unsigned) c); } } bson_validate_flags_t Document validation options Synopsis #include <bson/bson-types.h> typedef enum { BSON_VALIDATE_NONE = 0, BSON_VALIDATE_UTF8 = (1 << 0), BSON_VALIDATE_DOLLAR_KEYS = (1 << 1), BSON_VALIDATE_DOT_KEYS = (1 << 2), BSON_VALIDATE_UTF8_ALLOW_NULL = (1 << 3), BSON_VALIDATE_EMPTY_KEYS = (1 << 4), } bson_validate_flags_t; Description bson_validate_flags_t is a set of binary flags which may be combined to specify a level of BSON document validation. A value of 0, false, or BSON_VALIDATE_NONE equivalently requests the minimum applicable level of validation. In the context of validation APIs bson_validate(), bson_validate_with_error(), and bson_validate_with_error_and_offset() the minimum validation still guarantees that a document can be success- fully traversed by bson_iter_visit_all(). Higher level APIs using this type may have different minimum validation levels. For example, libmongoc functions that take bson_vali- date_flags_t use 0 to mean the document contents are not visited and malformed headers will not be detected by the client. Each defined flag aside from BSON_VALIDATE_NONE describes an optional validation feature that may be enabled, alone or in combination with other features: • BSON_VALIDATE_NONE Minimum level of validation; in libbson, validates element headers. • BSON_VALIDATE_UTF8 All keys and string values are checked for invalid UTF-8. • BSON_VALIDATE_UTF8_ALLOW_NULL String values are allowed to have em- bedded NULL bytes. • BSON_VALIDATE_DOLLAR_KEYS Prohibit keys that start with $ outside of a "DBRef" subdocument. • BSON_VALIDATE_DOT_KEYS Prohibit keys that contain . anywhere in the string. • BSON_VALIDATE_EMPTY_KEYS Prohibit zero-length keys. SEE ALSO: bson_validate(), bson_validate_with_error(), bson_validate_with_error_and_offset(). bson_visitor_t can be used for custom validation, Example Custom Validation. bson_value_t BSON Boxed Container Type Synopsis #include <bson/bson.h> typedef struct _bson_value_t { bson_type_t value_type; union { bson_oid_t v_oid; int64_t v_int64; int32_t v_int32; int8_t v_int8; double v_double; bool v_bool; int64_t v_datetime; struct { uint32_t timestamp; uint32_t increment; } v_timestamp; struct { uint32_t len; char *str; } v_utf8; struct { uint32_t data_len; uint8_t *data; } v_doc; struct { uint32_t data_len; uint8_t *data; bson_subtype_t subtype; } v_binary; struct { char *regex; char *options; } v_regex; struct { char *collection; uint32_t collection_len; bson_oid_t oid; } v_dbpointer; struct { uint32_t code_len; char *code; } v_code; struct { uint32_t code_len; char *code; uint32_t scope_len; uint8_t *scope_data; } v_codewscope; struct { uint32_t len; char *symbol; } v_symbol; bson_decimal128_t v_decimal128; } value; } bson_value_t; Description The bson_value_t structure is a boxed type for encapsulating a runtime determined type. Example const bson_value_t *value; value = bson_iter_value (&iter); if (value->value_type == BSON_TYPE_INT32) { printf ("%d\n", value->value.v_int32); } bson_visitor_t Synopsis #include <bson/bson.h> typedef struct { /* run before / after descending into a document */ bool (*visit_before) (const bson_iter_t *iter, const char *key, void *data); bool (*visit_after) (const bson_iter_t *iter, const char *key, void *data); /* corrupt BSON, or unsupported type and visit_unsupported_type not set */ void (*visit_corrupt) (const bson_iter_t *iter, void *data); /* normal bson field callbacks */ bool (*visit_double) (const bson_iter_t *iter, const char *key, double v_double, void *data); bool (*visit_utf8) (const bson_iter_t *iter, const char *key, size_t v_utf8_len, const char *v_utf8, void *data); bool (*visit_document) (const bson_iter_t *iter, const char *key, const bson_t *v_document, void *data); bool (*visit_array) (const bson_iter_t *iter, const char *key, const bson_t *v_array, void *data); bool (*visit_binary) (const bson_iter_t *iter, const char *key, bson_subtype_t v_subtype, size_t v_binary_len, const uint8_t *v_binary, void *data); /* normal field with deprecated "Undefined" BSON type */ bool (*visit_undefined) (const bson_iter_t *iter, const char *key, void *data); bool (*visit_oid) (const bson_iter_t *iter, const char *key, const bson_oid_t *v_oid, void *data); bool (*visit_bool) (const bson_iter_t *iter, const char *key, bool v_bool, void *data); bool (*visit_date_time) (const bson_iter_t *iter, const char *key, int64_t msec_since_epoch, void *data); bool (*visit_null) (const bson_iter_t *iter, const char *key, void *data); bool (*visit_regex) (const bson_iter_t *iter, const char *key, const char *v_regex, const char *v_options, void *data); bool (*visit_dbpointer) (const bson_iter_t *iter, const char *key, size_t v_collection_len, const char *v_collection, const bson_oid_t *v_oid, void *data); bool (*visit_code) (const bson_iter_t *iter, const char *key, size_t v_code_len, const char *v_code, void *data); bool (*visit_symbol) (const bson_iter_t *iter, const char *key, size_t v_symbol_len, const char *v_symbol, void *data); bool (*visit_codewscope) (const bson_iter_t *iter, const char *key, size_t v_code_len, const char *v_code, const bson_t *v_scope, void *data); bool (*visit_int32) (const bson_iter_t *iter, const char *key, int32_t v_int32, void *data); bool (*visit_timestamp) (const bson_iter_t *iter, const char *key, uint32_t v_timestamp, uint32_t v_increment, void *data); bool (*visit_int64) (const bson_iter_t *iter, const char *key, int64_t v_int64, void *data); bool (*visit_maxkey) (const bson_iter_t *iter, const char *key, void *data); bool (*visit_minkey) (const bson_iter_t *iter, const char *key, void *data); /* if set, called instead of visit_corrupt when an apparently valid BSON * includes an unrecognized field type (reading future version of BSON) */ void (*visit_unsupported_type) (const bson_iter_t *iter, const char *key, uint32_t type_code, void *data); bool (*visit_decimal128) (const bson_iter_t *iter, const char *key, const bson_decimal128_t *v_decimal128, void *data); void *padding[7]; } bson_visitor_t bson_visitor_t; Description The bson_visitor_t structure provides a series of callbacks that can be called while iterating a BSON document. This may simplify the conver- sion of a bson_t to a higher level language structure. If the optional callback visit_unsupported_type is set, it is called instead of visit_corrupt in the specific case of an unrecognized field type. (Parsing is aborted in either case.) Use this callback to report an error like "unrecognized type" instead of simply "corrupt BSON". This future-proofs code that may use an older version of libbson to parse future BSON formats. Basic Example #include <bson/bson.h> #include <stdio.h> static bool my_visit_before (const bson_iter_t *iter, const char *key, void *data) { int *count = (int *) data; (*count)++; /* returning true stops further iteration of the document */ return false; } static void count_fields (bson_t *doc) { bson_visitor_t visitor = {0}; bson_iter_t iter; int count = 0; visitor.visit_before = my_visit_before; if (bson_iter_init (&iter, doc)) { bson_iter_visit_all (&iter, &visitor, &count); } printf ("Found %d fields.\n", count); } The example below demonstrates how to set your own callbacks to provide information about the location of corrupt or unsupported BSON document entries. Example Corruption Check #include <bson/bson.h> #include <stdio.h> typedef struct { ssize_t *err_offset; } my_state_t; static void my_visit_corrupt (const bson_iter_t *iter, void *data) { *(((my_state_t *) data)->err_offset) = iter->off; } static void my_visit_unsupported_type (const bson_iter_t *iter, const char *key, uint32_t type_code, void *data) { *(((my_state_t *) data)->err_offset) = iter->off; } static void find_error_location (bson_t *doc) { bson_visitor_t visitors = {0}; bson_iter_t iter; my_state_t state; ssize_t err_offset = -1; visitors.visit_corrupt = my_visit_corrupt; visitors.visit_unsupported_type = my_visit_unsupported_type; /* provide additional visitors as needed based on your requirements */ state.err_offset = &err_offset; if (!bson_iter_init (&iter, doc)) { printf ("Could not initialize iterator!"); exit (1); } if (bson_iter_visit_all (&iter, &visitors, &state) || err_offset != -1) { printf ("Found error at offset %d.\n", err_offset); } else { printf ("BSON document had no errors.\n"); } } The example below demonstrates how to use a visitor to validate a BSON document's maximum depth. Example Custom Validation bson-check-depth.c /* Reports the maximum nested depth of a BSON document. */ #include <bson/bson.h> #include <assert.h> #include <inttypes.h> #include <stdio.h> #include <stdlib.h> typedef struct { uint32_t depth; uint32_t max_depth; bool valid; } check_depth_t; bool _check_depth_document (const bson_iter_t *iter, const char *key, const bson_t *v_document, void *data); static const bson_visitor_t check_depth_funcs = { NULL, NULL, NULL, NULL, NULL, _check_depth_document, _check_depth_document, NULL, }; bool _check_depth_document (const bson_iter_t *iter, const char *key, const bson_t *v_document, void *data) { check_depth_t *state = (check_depth_t *) data; bson_iter_t child; BSON_UNUSED (iter); BSON_UNUSED (key); if (!bson_iter_init (&child, v_document)) { fprintf (stderr, "corrupt\n"); return true; /* cancel */ } state->depth++; if (state->depth > state->max_depth) { state->valid = false; return true; /* cancel */ } bson_iter_visit_all (&child, &check_depth_funcs, state); state->depth--; return false; /* continue */ } void check_depth (const bson_t *bson, uint32_t max_depth) { bson_iter_t iter; check_depth_t state = {0}; if (!bson_iter_init (&iter, bson)) { fprintf (stderr, "corrupt\n"); } state.valid = true; state.max_depth = max_depth; _check_depth_document (&iter, NULL, bson, &state); if (!state.valid) { printf ("document exceeds maximum depth of %" PRIu32 "\n", state.max_depth); } else { char *as_json = bson_as_canonical_extended_json (bson, NULL); printf ("document %s ", as_json); printf ("is valid\n"); bson_free (as_json); } } int main (int argc, char **argv) { bson_reader_t *bson_reader; const bson_t *bson; bool reached_eof; bson_error_t error; if (argc != 3) { fprintf (stderr, "usage: %s FILE MAX_DEPTH\n", argv[0]); fprintf (stderr, "Checks that the depth of the BSON contained in FILE\n"); fprintf (stderr, "does not exceed MAX_DEPTH\n"); } const char *const filename = argv[1]; const int max_depth = atoi (argv[2]); bson_reader = bson_reader_new_from_file (filename, &error); if (!bson_reader) { printf ("could not read %s: %s\n", filename, error.message); return 1; } BSON_ASSERT (max_depth >= 0 && (uint64_t) max_depth <= UINT32_MAX); while ((bson = bson_reader_read (bson_reader, &reached_eof))) { check_depth (bson, (uint32_t) max_depth); } if (!reached_eof) { printf ("error reading BSON\n"); } bson_reader_destroy (bson_reader); return 0; } bson_writer_t Bulk BSON serialization Abstraction Synopsis #include <bson/bson.h> typedef struct _bson_writer_t bson_writer_t; bson_writer_t * bson_writer_new (uint8_t **buf, size_t *buflen, size_t offset, bson_realloc_func realloc_func, void *realloc_func_ctx); void bson_writer_destroy (bson_writer_t *writer); Description The bson_writer_t API provides an abstraction for serializing many BSON documents to a single memory region. The memory region may be dynami- cally allocated and re-allocated as more memory is demanded. This can be useful when building network packets from a high-level language. For example, you can serialize a Python Dictionary directly to a single buffer destined for a TCP packet. Example #include <bson/bson.h> int main (int argc, char *argv[]) { bson_writer_t *writer; uint8_t *buf = NULL; size_t buflen = 0; bson_t *doc; writer = bson_writer_new (&buf, &buflen, 0, bson_realloc_ctx, NULL); for (i = 0; i < 1000; i++) { bson_writer_begin (writer, &doc); BSON_APPEND_INT32 (&doc, "i", i); bson_writer_end (writer); } bson_writer_destroy (writer); bson_free (buf); return 0; } System Clock BSON Clock Abstraction Synopsis int64_t bson_get_monotonic_time (void); int bson_gettimeofday (struct timeval *tv); Description The clock abstraction in Libbson provides a cross-platform way to han- dle timeouts within the BSON library. It abstracts the differences in implementations of gettimeofday() as well as providing a monotonic (in- crementing only) clock in microseconds. Memory Management BSON Memory Abstraction. Description Libbson contains a lightweight memory abstraction to make portability to new platforms easier. Additionally, it helps us integrate with in- teresting higher-level languages. One caveat, however, is that Libbson is not designed to deal with Out of Memory (OOM) situations. Doing so requires extreme diligence throughout the application stack that has rarely been implemented correctly. This may change in the future. As it stands now, Libbson will abort() under OOM situations. To aid in language binding integration, Libbson allows for setting a custom memory allocator via bson_mem_set_vtable(). This allocation may be reversed via bson_mem_restore_vtable(). Libbson Versioning Versioning Macros and Functions Macros The following preprocessor macros can be used to perform various checks based on the version of the library you are compiling against. This may be useful if you only want to enable a feature on a certain version of the library. Synopsis #define BSON_CHECK_VERSION(major, minor, micro) #define BSON_MAJOR_VERSION (1) #define BSON_MINOR_VERSION (4) #define BSON_MICRO_VERSION (1) #define BSON_VERSION_S "1.4.1" #define BSON_VERSION_HEX \ (BSON_MAJOR_VERSION << 24 | BSON_MINOR_VERSION << 16 | \ BSON_MICRO_VERSION << 8) Only compile a block on Libbson 1.1.0 and newer. #if BSON_CHECK_VERSION(1, 1, 0) static void do_something (void) { } #endif Libbson Legacy Extended JSON libbson can produce a non-portable Legacy Extended JSON format. WARNING: Use of the Legacy Extended JSON format is discouraged. Prefer Canon- ical Extended JSON or Relaxed Extended JSON for portability. MongoDB Extended JSON (v2) describes the preferred Relaxed Extended JSON format and Canonical Extended Formats libbson's Legacy Extended JSON format matches Relaxed Extended JSON with the following exceptions. Notation is borrowed from MongoDB Ex- tended JSON (v2): +------------------------+-----------------------------------------------------------------------------+ | Type | Legacy Extended JSON | +------------------------+-----------------------------------------------------------------------------+ | Binary | | | | { "$binary": "<payload>", "$type": "<t>" } | +------------------------+-----------------------------------------------------------------------------+ | Date | | | | { "$date" : "<millis>" } | +------------------------+-----------------------------------------------------------------------------+ | Regular Expression | | | | { "$regex" : "<regexPattern>", "$options" : "<options>" } | +------------------------+-----------------------------------------------------------------------------+ | DBPointer (deprecated) | | | | { "$ref" : "<collection namespace>", "$id" : "<ObjectId bytes>" } | +------------------------+-----------------------------------------------------------------------------+ | Symbol (deprecated) | | | | "<string>" | +------------------------+-----------------------------------------------------------------------------+ | Double infinity | infinity or inf without quotes. Implementation defined. Produces invalid | | | JSON. | +------------------------+-----------------------------------------------------------------------------+ | Double NaN | nan or nan(n-char-sequence). Implementation defined. Produces invalid JSON. | +------------------------+-----------------------------------------------------------------------------+ AUTHOR MongoDB, Inc COPYRIGHT 2009-present, MongoDB, Inc. 1.30.2 Apr 12, 2025 BSON_REFERENCE(3)
LIBBSON - API | AUTHOR | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=bson_reference&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>