Section 3: library functions
NAME bson_string_append_c() – Appends c to the string builder string. SYNOPSIS void bson_string_append_c(bson_string_t *string, char str); PARAMETERS string A bson_string_t \&. str An ASCII char. DESCRIPTION Appends c to the string builder string \&. COLOPHON This page is part of libbson. Please report any bugs at https://jira.mongodb.org/browse/CDRIVER. Index
NAME bson_string_append() – Appends the ASCII or UTF-8 encoded string str to string. This is not suitable for embedding NULLs in strings. SYNOPSIS void bson_string_append(bson_string_t *string, const char *str); PARAMETERS string A bson_string_t \&. str A string. DESCRIPTION Appends the ASCII or UTF-8 encoded string str to string \&. This is not suitable for embedding…
NAME bson_strfreev() – This will free each string in a NULL-terminated array of strings and then the array itself. SYNOPSIS void bson_strfreev(char **strv); PARAMETERS strv A NULL-terminated array of strings to free, including the array. DESCRIPTION This will free each string in a NULL-terminated array of strings and then the array itself. COLOPHON This page…
NAME bson_strerror_r() – This is a portability wrapper around strerror(). SYNOPSIS char * bson_strerror_r(int err_code, char *buf, size_t buflen); PARAMETERS err_code An errno. buf A location to store the string. buflen The size of buf \&. DESCRIPTION This is a portability wrapper around strerror(3) \&. RETURNS The passed in buf parameter or an internal string….
NAME bson_strdupv_printf() – This function is like bson_strdup_printf() except takes a va_list of parameters. SYNOPSIS char * bson_strdupv_printf(const char *format, va_list args) BSON_GNUC_PRINTF(1, 0); PARAMETERS format A printf style format string. args A va_list. DESCRIPTION This function is like bson_strdup_printf(3) except takes a va_list of parameters. RETURNS A newly allocated string that should be freed…
NAME bson_strdup_printf() – This function performs a printf style format but into a newly allocated string. SYNOPSIS char * bson_strdup_printf(const char *format, …) BSON_GNUC_PRINTF(1, 2); PARAMETERS format A printf style format string. DESCRIPTION This function performs a printf style format but into a newly allocated string. RETURNS A newly allocated string that should be freed…
NAME bson_strdup() – Copies str into a new string. If str is NULL, then NULL is returned. SYNOPSIS char * bson_strdup(const char *str); PARAMETERS str A string. DESCRIPTION Copies str into a new string. If str is NULL, then NULL is returned. RETURNS A newly allocated string that should be freed with bson_free(). COLOPHON This…
NAME bson_snprintf() – This is a portable wrapper around snprintf(). It also enforces a trailing in the resulting string. SYNOPSIS int bson_snprintf(char *str, size_t size, const char *format, …) BSON_GNUC_PRINTF(3, 4); PARAMETERS str The destination buffer. size The size of str \&. format A printf style format string. DESCRIPTION This is a portable wrapper…
NAME bson_sized_new() – The bson_sized_new() function shall create a new bson_t on the heap with a preallocated buffer. This is useful if you have a good idea of the size of the resulting document. SYNOPSIS bson_t * bson_sized_new (size_t size); PARAMETERS size The size to pre-allocate for the underlying buffer. DESCRIPTION The bson_sized_new(3) function shall…
NAME bson_set_error() – This is a helper function to set the parameters of a bson_error_t. It handles the case where error is NULL by doing nothing. SYNOPSIS void bson_set_error(bson_error_t *error, uint32_t domain, uint32_t code, const char *format, …) BSON_GNUC_PRINTF(4, 5); PARAMETERS error A bson_error_t \&. domain A uint32_t \&. code A uint32_t \&. format A…
NAME bson_reinit() – The bson_reinit() function shall be equivalent to calling bson_destroy() and bson_init(). SYNOPSIS void bson_reinit(bson_t *b); PARAMETERS b A bson_t \&. DESCRIPTION The bson_reinit(3) function shall be equivalent to calling bson_destroy(3) and bson_init(3) \&. However, if the bson_t structure contains a malloc()’d buffer, it may be reused. To be certain that any buffer…
NAME bson_realloc_func – This is a prototype for pluggable realloc functions used through the Libbson library. If you wish to use a custom allocator this is one way to do it. Additionally, bson_realloc_ctx() is a default implementation of this prototype. SYNOPSIS typedef void *(*bson_realloc_func)(void *mem, size_t num_bytes, void *ctx); PARAMETERS mem A memory region. num_bytes…
NAME bson_realloc_ctx() – This function is identical to bson_realloc() except it takes a context parameter. This is useful when working with pooled or specific memory allocators. SYNOPSIS void * bson_realloc_ctx(void *mem, size_t num_bytes, void *ctx); PARAMETERS mem A memory region. num_bytes A size_t containing the requested size. ctx A consumer-specific pointer or NULL \&. DESCRIPTION…
NAME bson_realloc() – This is a portable realloc() wrapper. SYNOPSIS void * bson_realloc(void *mem, size_t num_bytes); PARAMETERS mem A memory region. num_bytes A size_t containing the new requested size. DESCRIPTION This is a portable realloc(3) wrapper. In general, this function will return an allocation at least sizeof(void*) bytes or bigger. If num_bytes is 0, then…
NAME bson_reader_tell() – Tells the current position within the underlying stream. SYNOPSIS off_t bson_reader_tell (bson_reader_t *reader); PARAMETERS reader A bson_reader_t \&. DESCRIPTION Tells the current position within the underlying stream. RETURNS -1 on failure, otherwise the offset within the underlying stream. COLOPHON This page is part of libbson. Please report any bugs at https://jira.mongodb.org/browse/CDRIVER. Index
NAME bson_reader_t – Streaming BSON Document Reader SYNOPSIS #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); DESCRIPTION bson_reader_t is a structure used for reading a sequence of BSON documents. The…
NAME bson_reader_set_read_func() – Sets the function to read more data from the underlying stream in a custom bson_reader_t. SYNOPSIS void bson_reader_set_read_func (bson_reader_t *reader, bson_reader_read_func_t func); PARAMETERS reader A bson_reader_t \&. func A bson_reader_read_func_t \&. DESCRIPTION Sets the function to read more data from the underlying stream in a custom bson_reader_t. COLOPHON This page is part…
NAME bson_reader_set_destroy_func() – Allows for setting a callback to be executed when a reader is destroyed. This should only be used by implementations implementing their own read callbacks. SYNOPSIS void bson_reader_set_destroy_func (bson_reader_t *reader, bson_reader_destroy_func_t func); PARAMETERS reader A bson_reader_t \&. func A bson_reader_destroy_func_t \&. DESCRIPTION Allows for setting a callback to be executed when a…
NAME bson_reader_read_func_t – A callback function that will be called by bson_reader_t to read the next chunk of data from the underlying opaque file descriptor. SYNOPSIS typedef ssize_t (*bson_reader_read_func_t)(void *handle, void *buf, size_t count); PARAMETERS handle The handle to read from. buf The buffer to read into. count The number of bytes to read. DESCRIPTION…
NAME bson_reader_read() – The bson_reader_read() function shall read the next document from the underlying file-descriptor or buffer. SYNOPSIS const bson_t * bson_reader_read (bson_reader_t *reader, bool *reached_eof); PARAMETERS reader A bson_reader_t \&. reached_eof A UNKNOWN. DESCRIPTION The bson_reader_read(3) function shall read the next document from the underlying file-descriptor or buffer. If there are no further documents…