.\" Man page generated from reStructuredText.
.
.TH "BSON_STREAMING_BSON" "3" "Jun 04, 2021" "1.17.6" "libbson"
.SH NAME
bson_streaming_bson \- Streaming BSON
.
.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
..
.sp
\fBbson_reader_t\fP provides a streaming reader which can be initialized with a filedescriptor or memory region. \fBbson_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.)
.SH READING FROM A BSON STREAM
.sp
\fBbson_reader_t\fP provides a convenient API to read sequential BSON documents from a file\-descriptor or memory buffer. The \fBbson_reader_read()\fP function will read forward in the underlying stream and return a \fBbson_t\fP that can be inspected and iterated upon.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#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 ("mycollection.bson", &error);

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

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

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

   bson_reader_destroy (reader);

   return 0;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See \fBbson_reader_new_from_fd()\fP, \fBbson_reader_new_from_file()\fP, and \fBbson_reader_new_from_data()\fP for more information.
.SH WRITING A SEQUENCE OF BSON DOCUMENTS
.sp
\fBbson_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 \fBbson_writer_begin()\fP and \fBbson_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
.nf
.ft C
#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, "i", i);
      assert (r);

      bson_writer_end (writer);
   }

   bson_free (buf);

   return 0;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See \fBbson_writer_new()\fP for more information.
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.