.\" Man page generated from reStructuredText.
.
.
.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
..
.TH "BSON_GUIDES" "3" "Feb 22, 2024" "1.26.0" "libbson"
.SH STREAMING BSON
.sp
\fI\%bson_reader_t\fP provides a streaming reader which can be initialized with a filedescriptor or memory region. \fI\%bson_writer_t\fP provides a streaming writer which can be initialized with a memory region. (Streaming BSON to a file descriptor is not yet supported.)
.SS Reading from a BSON Stream
.sp
\fI\%bson_reader_t\fP provides a convenient API to read sequential BSON documents from a file\-descriptor or memory buffer. The \fI\%bson_reader_read()\fP function will read forward in the underlying stream and return a \fI\%bson_t\fP that can be inspected and iterated upon.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#include <stdio.h>
#include <bson/bson.h>

int
main (int argc, char *argv[])
{
   bson_reader_t *reader;
   const bson_t *doc;
   bson_error_t error;
   bool eof;

   reader = bson_reader_new_from_file (\(dqmycollection.bson\(dq, &error);

   if (!reader) {
      fprintf (stderr, \(dqFailed to open file.\en\(dq);
      return 1;
   }

   while ((doc = bson_reader_read (reader, &eof))) {
      char *str = bson_as_canonical_extended_json (doc, NULL);
      printf (\(dq%s\en\(dq, str);
      bson_free (str);
   }

   if (!eof) {
      fprintf (stderr,
               \(dqcorrupted bson document found at %u\en\(dq,
               (unsigned) bson_reader_tell (reader));
   }

   bson_reader_destroy (reader);

   return 0;
}
.EE
.UNINDENT
.UNINDENT
.sp
See \fI\%bson_reader_new_from_fd()\fP, \fI\%bson_reader_new_from_file()\fP, and \fI\%bson_reader_new_from_data()\fP for more information.
.SS Writing a sequence of BSON Documents
.sp
\fI\%bson_writer_t\fP provides a convenient API to write a sequence of BSON documents to a memory buffer that can grow with \fBrealloc()\fP\&. The \fI\%bson_writer_begin()\fP and \fI\%bson_writer_end()\fP functions will manage the underlying buffer while building the sequence of documents.
.sp
This could also be useful if you want to write to a network packet while serializing the documents from a higher level language, (but do so just after the packets header).
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#include <stdio.h>
#include <bson/bson.h>
#include <assert.h>

int
main (int argc, char *argv[])
{
   bson_writer_t *writer;
   bson_t *doc;
   uint8_t *buf = NULL;
   size_t buflen = 0;
   bool r;
   int i;

   writer = bson_writer_new (&buf, &buflen, 0, bson_realloc_ctx, NULL);

   for (i = 0; i < 10000; i++) {
      r = bson_writer_begin (writer, &doc);
      assert (r);

      r = BSON_APPEND_INT32 (doc, \(dqi\(dq, i);
      assert (r);

      bson_writer_end (writer);
   }

   bson_free (buf);

   return 0;
}
.EE
.UNINDENT
.UNINDENT
.sp
See \fI\%bson_writer_new()\fP for more information.
.SH JSON
.sp
Libbson provides routines for converting to and from the JSON format. In particular, it supports the \fI\%MongoDB extended JSON\fP format.
.SS Converting BSON to JSON
.sp
There are often times where you might want to convert a BSON document to JSON. It is convenient for debugging as well as an interchange format. To help with this, Libbson contains the functions \fI\%bson_as_canonical_extended_json()\fP and \fI\%bson_as_relaxed_extended_json()\fP\&. The canonical format preserves BSON type information for values that may have ambiguous representations in JSON (e.g. numeric types).
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t *b;
size_t len;
char *str;

b = BCON_NEW (\(dqa\(dq, BCON_INT32 (1));

str = bson_as_canonical_extended_json (b, &len);
printf (\(dq%s\en\(dq, str);
bson_free (str);

bson_destroy (b);
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{ \(dqa\(dq : { \(dq$numberInt\(dq: \(dq1\(dq } }
.EE
.UNINDENT
.UNINDENT
.sp
The relaxed format prefers JSON primitives for numeric values and may be used if type fidelity is not required.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t *b;
size_t len;
char *str;

b = BCON_NEW (\(dqa\(dq, BCON_INT32 (1));

str = bson_as_relaxed_extended_json (b, &len);
printf (\(dq%s\en\(dq, str);
bson_free (str);

bson_destroy (b);
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{ \(dqa\(dq : 1 }
.EE
.UNINDENT
.UNINDENT
.SS Converting JSON to BSON
.sp
Converting back from JSON is also useful and common enough that we added \fI\%bson_init_from_json()\fP and \fI\%bson_new_from_json()\fP\&.
.sp
The following example creates a new \fI\%bson_t\fP from the JSON string \fB{\(dqa\(dq:1}\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t *b;
bson_error_t error;

b = bson_new_from_json (\(dq{\e\(dqa\e\(dq:1}\(dq, \-1, &error);

if (!b) {
   printf (\(dqError: %s\en\(dq, error.message);
} else {
   bson_destroy (b);
}
.EE
.UNINDENT
.UNINDENT
.SS Streaming JSON Parsing
.sp
Libbson provides \fI\%bson_json_reader_t\fP to allow for parsing a sequence of JSON documents into BSON. The interface is similar to \fI\%bson_reader_t\fP but expects the input to be in the \fI\%MongoDB extended JSON\fP format.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/*
 * Copyright 2013 MongoDB, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the \(dqLicense\(dq);
 * 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 \(dqAS IS\(dq 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, \(dqusage: %s FILE...\en\(dq, 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, \(dq\-\(dq)) {
         reader = bson_json_reader_new_from_fd (STDIN_FILENO, false);
      } else {
         if (!(reader = bson_json_reader_new_from_file (filename, &error))) {
            fprintf (
               stderr, \(dqFailed to open \e\(dq%s\e\(dq: %s\en\(dq, 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, \(dqError in json parsing:\en%s\en\(dq, error.message);
            abort ();
         }

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

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

   return 0;
}
.EE
.UNINDENT
.UNINDENT
.SS Examples
.sp
The following example reads BSON documents from \fBstdin\fP and prints them to \fBstdout\fP as JSON.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/*
 * Copyright 2013 MongoDB, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the \(dqLicense\(dq);
 * 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 \(dqAS IS\(dq 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, \(dqusage: %s [FILE | \-]...\enUse \- for STDIN.\en\(dq, 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, \(dq\-\(dq) == 0) {
         reader = bson_reader_new_from_fd (STDIN_FILENO, false);
      } else {
         if (!(reader = bson_reader_new_from_file (filename, &error))) {
            fprintf (
               stderr, \(dqFailed to open \e\(dq%s\e\(dq: %s\en\(dq, 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, \(dq%s\en\(dq, str);
         bson_free (str);
      }

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

   return 0;
}
.EE
.UNINDENT
.UNINDENT
.SH BSON_T LIFETIMES
.sp
A \fI\%bson_t\fP may contain its data directly or may contain pointers to heap\-allocated memory. Overwriting an existing \fI\%bson_t\fP
or allowing a stack\-allocated \fI\%bson_t\fP to go out of scope may cause a memory leak. A \fI\%bson_t\fP should always be destroyed with
\fI\%bson_destroy()\fP\&.
.SS \fI\%bson_t\fP out parameters
.sp
A \fI\%bson_t\fP pointer used as an out parameter must point to valid overwritable storage for a new \fI\%bson_t\fP which must be one of:
.INDENT 0.0
.IP 1. 3
Uninitialized storage for a \fI\%bson_t\fP\&.
.IP 2. 3
A zero\-initialized \fI\%bson_t\fP object.
.IP 3. 3
A \fI\%bson_t\fP object initialized with \fBBSON_INITIALIZER\fP\&.
.IP 4. 3
A \fI\%bson_t\fP object not created with \fI\%bson_new()\fP that was destroyed with \fI\%bson_destroy()\fP\&.
.UNINDENT
.sp
This can be on the stack:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t stack_doc = BSON_INITIALIZER;
example_get_doc (&stack_doc);
bson_destroy (&stack_doc);
.EE
.UNINDENT
.UNINDENT
.sp
Or on the heap:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t *heap_doc = bson_malloc (sizeof (bson_t));
example_get_doc (heap_doc);
bson_destroy (heap_doc);
bson_free (heap_doc);
.EE
.UNINDENT
.UNINDENT
.sp
Omitting \fI\%bson_destroy()\fP in either case may cause memory leaks.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Passing a \fI\%bson_t\fP pointer obtained from \fI\%bson_new()\fP as an out parameter will result in a leak of the \fI\%bson_t\fP struct.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t *heap_doc = bson_new ();
example_get_doc (heap_doc);
bson_destroy (heap_doc); // Leaks the \(gabson_t\(ga struct!
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.