BSON_T OUT PARAMETERS

       A bson_t pointer used as an out parameter must point to valid overwritable storage for a new bson_t which
       must be one of:

       1. Uninitialized storage for a bson_t.

       2. A zero-initialized bson_t object.

       3. A bson_t object initialized with BSON_INITIALIZER.

       4. A bson_t object not created with bson_new() that was destroyed with bson_destroy().

       This can be on the stack:

          bson_t stack_doc = BSON_INITIALIZER;
          example_get_doc (&stack_doc);
          bson_destroy (&stack_doc);

       Or on the heap:

          bson_t *heap_doc = bson_malloc (sizeof (bson_t));
          example_get_doc (heap_doc);
          bson_destroy (heap_doc);
          bson_free (heap_doc);

       Omitting bson_destroy() in either case may cause memory leaks.

       WARNING:
          Passing a bson_t pointer obtained from bson_new() as an out parameter will result in  a  leak  of  the
          bson_t struct.

              bson_t *heap_doc = bson_new ();
              example_get_doc (heap_doc);
              bson_destroy (heap_doc); // Leaks the `bson_t` struct!

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2017-present, MongoDB, Inc

1.26.0                                            Mar 31, 2024                                 BSON_LIFETIMES(3)