.\" Man page generated from reStructuredText.
.
.TH "BSON_API" "3" "May 23, 2017" "1.6.3" "Libbson"
.SH NAME
bson_api \- API Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH BSON_T
.sp
BSON Document Abstraction
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <bson.h>

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);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The \fBbson_t\fP structure represents a BSON document. This structure manages the underlying BSON encoded buffer. For mutable documents, it can append new data to the document.
.SS Performance Notes
.sp
The \fBbson_t\fP structure attempts to use an inline allocation within the structure to speed up performance of small documents. When this internal buffer has been exhausted, a heap allocated buffer will be dynamically allocated. Therefore, it is essential to call \fBbson_destroy()\fP on allocated documents.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_CONTEXT_T
.sp
BSON OID Generation Context
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <bson.h>

typedef enum {
   BSON_CONTEXT_NONE = 0,
   BSON_CONTEXT_THREAD_SAFE = (1 << 0),
   BSON_CONTEXT_DISABLE_HOST_CACHE = (1 << 1),
   BSON_CONTEXT_DISABLE_PID_CACHE = (1 << 2),
#ifdef BSON_HAVE_SYSCALL_TID
   BSON_CONTEXT_USE_TASK_ID = (1 << 3),
#endif
} bson_context_flags_t;

typedef struct _bson_context_t bson_context_t;

bson_context_t *
bson_context_get_default (void) BSON_GNUC_CONST;
bson_context_t *
bson_context_new (bson_context_flags_t flags);
void
bson_context_destroy (bson_context_t *context);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The \fBbson_context_t\fP structure is context for generation of BSON Object IDs. This context allows for specialized overriding of how ObjectIDs are generated based on the applications requirements. For example, disabling of PID caching can be configured if the application cannot detect when a call to \fBfork()\fP has occurred.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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_DISABLE_PID_CACHE |
                           BSON_CONTEXT_THREAD_SAFE);
   bson_oid_init (&oid, ctx);

   bson_context_destroy (ctx);

   return 0;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_DECIMAL128_T
.sp
BSON Decimal128 Abstraction
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <bson.h>

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;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The \fBbson_decimal128_t\fP structure
represents the IEEE\-754 Decimal128 data type.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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\en", string);

   return 0;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_ERROR_T
.sp
BSON Error Encapsulation
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <bson.h>

typedef struct {
   uint32_t domain;
   uint32_t code;
   char message[504];
} bson_error_t;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The \fBbson_error_t\fP structure is used as an out\-parameter to pass error information to the caller. It should be stack\-allocated and does not requiring freeing.
.sp
See Handling Errors\&.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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\en", error.domain, error.code, error.message);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_ITER_T
.sp
BSON Document Iterator
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <bson.h>

typedef struct {
   /*< private >*/
} bson_iter_t;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
\fBbson_iter_t\fP is a structure used to iterate through the elements of a \fBbson_t\fP\&. 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 structure should be considered private and may change between releases, however the structure size will not change.
.sp
The \fBbson_t\fP \fIMUST\fP be valid for the lifetime of the iter and it is an error to modify the \fBbson_t\fP while using the iter.
.SS Examples
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bson_iter_t iter;

if (bson_iter_init (&iter, my_bson_doc)) {
   while (bson_iter_next (&iter)) {
      printf ("Found a field named: %s\en", bson_iter_key (&iter));
   }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bson_iter_t iter;

if (bson_iter_init (&iter, my_bson_doc) && bson_iter_find (&iter, "my_field")) {
   printf ("Found the field named: %s\en", bson_iter_key (&iter));
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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 \e"%s\e" in sub document.\en", bson_iter_key (&sub_iter));
   }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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\en", (int) bson_iter_type (&sub_iter));
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_JSON_READER_T
.sp
Bulk JSON to BSON conversion
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The \fBbson_json_reader_t\fP structure is used for reading a sequence of JSON documents and transforming them to \fBbson_t\fP documents.
.sp
This can often be useful if you want to perform bulk operations that are defined in a file containing JSON documents.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/*
 * Copyright 2013 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.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...\en", 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 \e"%s\e": %s\en", 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:\en%s\en", error.message);
            abort ();
         }

         if (fwrite (bson_get_data (&doc), 1, doc.len, stdout) != doc.len) {
            fprintf (stderr, "Failed to write to stdout, exiting.\en");
            exit (1);
         }
         bson_reinit (&doc);
      }

      bson_json_reader_destroy (reader);
      bson_destroy (&doc);
   }

   return 0;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_MD5_T
.sp
BSON MD5 Abstraction
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct {
   uint32_t count[2]; /* message length in bits, lsw first */
   uint32_t abcd[4];  /* digest buffer */
   uint8_t buf[64];   /* accumulate block */
} bson_md5_t;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
bson_md5_t encapsulates an implementation of the MD5 algorithm. This is used in OID generation for the MD5(hostname) bytes. It is also used by some libraries such as the MongoDB C driver.
.SH BSON_OID_T
.sp
BSON ObjectID Abstraction
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <bson.h>

typedef struct {
   uint8_t bytes[12];
} bson_oid_t;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The \fBbson_oid_t\fP structure contains the 12\-byte ObjectId notation defined by the \fI\%BSON ObjectID specification\fP\&.
.sp
ObjectId is a 12\-byte BSON type, constructed using:
.INDENT 0.0
.IP \(bu 2
a 4\-byte value representing the seconds since the Unix epoch (in Big Endian)
.IP \(bu 2
a 3\-byte machine identifier
.IP \(bu 2
a 2\-byte process id (Big Endian), and
.IP \(bu 2
a 3\-byte counter (Big Endian), starting with a random value.
.UNINDENT
.SS String Conversion
.sp
You can convert an Object ID to a string using \fBbson_oid_to_string()\fP and back with \fBbson_oid_init_from_string()\fP\&.
.SS Hashing
.sp
A \fBbson_oid_t\fP can be used in hashtables using the function \fBbson_oid_hash()\fP and \fBbson_oid_equal()\fP\&.
.SS Comparing
.sp
A \fBbson_oid_t\fP can be compared to another using \fBbson_oid_compare()\fP for \fBqsort()\fP style comparing and \fBbson_oid_equal()\fP for direct equality.
.SS Validating
.sp
You can validate that a string containing a hex\-encoded ObjectID is valid using the function \fBbson_oid_is_valid()\fP\&.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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\en", str);

   if (bson_oid_is_valid (str, sizeof str)) {
      bson_oid_init_from_string (&oid, str);
   }

   printf ("The UNIX time was: %u\en", (unsigned) bson_oid_get_time_t (&oid));

   return 0;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_READER_T
.sp
Streaming BSON Document Reader
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
\fBbson_reader_t\fP is a structure used for reading a sequence of BSON documents. The sequence can come from a file\-descriptor, memory region, or custom callbacks.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/*
 * Copyright 2013 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.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 | \-]...\enUse \- for STDIN.\en", 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 \e"%s\e": %s\en", filename, error.message);
            continue;
         }
      }

      /*
       * Convert each incoming document to JSON and print to stdout.
       */
      while ((b = bson_reader_read (reader, NULL))) {
         str = bson_as_json (b, NULL);
         fprintf (stdout, "%s\en", str);
         bson_free (str);
      }

      /*
       * Cleanup after our reader, which closes the file descriptor.
       */
      bson_reader_destroy (reader);
   }

   return 0;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_STRING_T
.sp
String Building Abstraction
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <bson.h>

typedef struct {
   char *str;
   uint32_t len;
   uint32_t alloc;
} bson_string_t;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
\fBbson_string_t\fP is an abstraction for building strings. As chunks are added to the string, allocations are performed in powers of two.
.sp
This API is useful if you need to build UTF\-8 encoded strings.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bson_string_t *str;

str = bson_string_new (NULL);
bson_string_append_printf (str, "%d %s %f\en", 0, "some string", 0.123);
printf ("%s\en", str\->str);

bson_string_free (str, true);
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_SUBTYPE_T
.sp
Binary Field Subtype
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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_USER = 0x80,
} bson_subtype_t;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
This enumeration contains the various subtypes that may be used in a binary field. See \fI\%http://bsonspec.org\fP for more information.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bson_t doc = BSON_INITIALIZER;

BSON_APPEND_BINARY (&doc, "binary", BSON_SUBTYPE_BINARY, data, data_len);
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_TYPE_T
.sp
BSON Type Enumeration
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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_MAXKEY = 0x7F,
   BSON_TYPE_MINKEY = 0xFF,
} bson_type_t;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The \fBbson_type_t\fP enumeration contains all of the types from the \fI\%BSON Specification\fP\&. It can be used to determine the type of a field at runtime.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bson_iter_t iter;

if (bson_iter_init_find (&iter, doc, "foo") &&
    (BSON_TYPE_INT32 == bson_iter_type (&iter))) {
   printf ("\(aqfoo\(aq is an int32.\en");
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_UINT32_TO_STRING()
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
size_t
bson_uint32_to_string (uint32_t value,
                       const char **strptr,
                       char *str,
                       size_t size);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See Array Element Key Building for example usage.
.SS Parameters
.INDENT 0.0
.IP \(bu 2
\fBvalue\fP: A uint32_t.
.IP \(bu 2
\fBstrptr\fP: A location for the resulting string pointer.
.IP \(bu 2
\fBstr\fP: A location to buffer the string.
.IP \(bu 2
\fBsize\fP: A size_t containing the size of \fBstr\fP\&.
.UNINDENT
.SS Description
.sp
Converts \fBvalue\fP to a string.
.sp
If \fBvalue\fP is from 0 to 999, it will use a constant string in the data section of the library.
.sp
If not, a string will be formatted using \fBstr\fP and \fBsnprintf()\fP\&.
.sp
\fBstrptr\fP will always be set. It will either point to \fBstr\fP or a constant string. Use this as your key.
.SS Returns
.sp
The number of bytes in the resulting string.
.SH BSON_UNICHAR_T
.sp
Unicode Character Abstraction
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
typedef uint32_t bson_unichar_t;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
\fBbson_unichar_t\fP 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.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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.\en", (unsigned) c);
   }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_VALUE_T
.sp
BSON Boxed Container Type
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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;
   } value;
} bson_value_t;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The \fBbson_value_t\fP structure is a boxed type for encapsulating a runtime determined type.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
const bson_value_t *value;

value = bson_iter_value (&iter);

if (value\->value_type == BSON_TYPE_INT32) {
   printf ("%d\en", value\->value.v_int32);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_VISITOR_T
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The \fBbson_visitor_t\fP structure provides a series of callbacks that can be called while iterating a BSON document. This may simplify the conversion of a \fBbson_t\fP to a higher level language structure.
.sp
If the optional callback \fBvisit_unsupported_type\fP is set, it is called instead of \fBvisit_corrupt\fP 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.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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.\en", count);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BSON_WRITER_T
.sp
Bulk BSON serialization Abstraction
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The \fBbson_writer_t\fP API provides an abstraction for serializing many BSON documents to a single memory region. The memory region may be dynamically 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.
.SS Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <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;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SYSTEM CLOCK
.sp
BSON Clock Abstraction
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
int64_t
bson_get_monotonic_time (void);
int
bson_gettimeofday (struct timeval *tv,
                   struct timezone *tz);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The clock abstraction in Libbson provides a cross\-platform way to handle timeouts within the BSON library. It abstracts the differences in implementations of \fBgettimeofday()\fP as well as providing a monotonic (incrementing only) clock in microseconds.
.SH MEMORY MANAGEMENT
.sp
BSON Memory Abstraction.
.SS Description
.sp
Libbson contains a lightweight memory abstraction to make portability to new platforms easier. Additionally, it helps us integrate with interesting higher\-level languages. One caveat, however, is that Libbson is not designed to deal with Out of Memory (OOM) situations. Doing so requires extreme dilligence throughout the application stack that has rarely been implemented correctly. This may change in the future. As it stands now, Libbson will \fBabort()\fP under OOM situations.
.sp
To aid in language binding integration, Libbson allows for setting a custom memory allocator via \fBbson_mem_set_vtable()\fP\&.  This allocation may be reversed via \fBbson_mem_restore_vtable()\fP\&.
.SH LIBBSON VERSIONING
.sp
Versioning Macros and Functions
.SS Macros
.sp
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.
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#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                                  \e
   (BSON_MAJOR_VERSION << 24 | BSON_MINOR_VERSION << 16 | \e
    BSON_MICRO_VERSION << 8)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Only compile a block on Libbson 1.1.0 and newer.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#if BSON_CHECK_VERSION(1, 1, 0)
static void
do_something (void)
{
}
#endif
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017, MongoDB, Inc
.\" Generated by docutils manpage writer.
.