1BSON_RESERVE_BUFFER(3)              libbson             BSON_RESERVE_BUFFER(3)
2
3
4

NAME

6       bson_reserve_buffer - bson_reserve_buffer()
7

SYNOPSIS

9          uint8_t *
10          bson_reserve_buffer (bson_t *bson, uint32_t size);
11

PARAMETERS

13       · bson: An initialized bson_t.
14
15       · size: The length in bytes of the new buffer.
16

DESCRIPTION

18       Grow the internal buffer of bson to size and set the document length to
19       size. Useful for eliminating copies when  reading  BSON  bytes  from  a
20       stream.
21
22       First, initialize bson with bson_init or bson_new, then call this func‐
23       tion. After it returns, the length of bson is set to size but its  con‐
24       tents  are uninitialized memory: you must fill the contents with a BSON
25       document of the correct length before any other operations.
26
27       The document must be freed with bson_destroy.
28

RETURNS

30       A pointer to the internal buffer, which is at least size bytes, or NULL
31       if the space could not be allocated.
32

EXAMPLE

34       Use bson_reserve_buffer to write a function that takes a bson_t pointer
35       and reads a file into it directly:
36
37          #include <stdio.h>
38          #include <bson/bson.h>
39
40          bool
41          read_into (bson_t *bson, FILE *fp)
42          {
43             uint8_t *buffer;
44             long size;
45
46             if (fseek (fp, 0L, SEEK_END) < 0) {
47                perror ("Couldn't get file size");
48                return 1;
49             }
50
51             size = ftell (fp);
52             if (size == EOF) {
53                perror ("Couldn't get file size");
54                return 1;
55             }
56
57             if (size > INT32_MAX) {
58                fprintf (stderr, "File too large\n");
59                return 1;
60             }
61
62             /* reserve buffer space - bson is temporarily invalid */
63             buffer = bson_reserve_buffer (bson, (uint32_t) size);
64             if (!buffer) {
65                fprintf (stderr, "Couldn't reserve %ld bytes", size);
66                return false;
67             }
68
69             /* read file directly into the buffer */
70             rewind (fp);
71             if (fread ((void *) buffer, 1, (size_t) size, fp) < (size_t) size) {
72                perror ("Couldn't read file");
73                return false;
74             }
75
76             return true;
77          }
78
79          int
80          main ()
81          {
82             FILE *fp;
83             char *json;
84
85             /* stack-allocated, initialized bson_t */
86             bson_t bson = BSON_INITIALIZER;
87
88             if (!(fp = fopen ("document.bson", "rb"))) {
89                perror ("Couldn't read file");
90                return 1;
91             }
92
93             read_into (&bson, fp);
94             fclose (fp);
95
96             json = bson_as_canonical_extended_json (&bson, NULL);
97             printf ("%s\n", json);
98
99             bson_free (json);
100             bson_destroy (&bson);
101
102             return 0;
103          }
104

AUTHOR

106       MongoDB, Inc
107

109       2017-present, MongoDB, Inc
110
111
112
113
1141.16.2                           Feb 25, 2020           BSON_RESERVE_BUFFER(3)
Impressum