PB_BYTES(3)

NAME
pb_bytes - protocol buffers bytes objects

LIBRARY
Protocol buffers library (libpicopb, -lpicopb)

SYNOPSIS
#include <pb.h>
size_t
pb_bytes_size(const struct pb_bytes *bytes);
const uint8_t *
pb_bytes_ptr(const struct pb_bytes *bytes, size_t *sizep);
uint8_t *
pb_bytes_ptr_mutable(const struct pb_bytes *bytes, size_t *sizep);
int
pb_bytes_alloc(struct pb_bytes *bytes, size_t size);
int
pb_bytes_set_copy(struct pb_bytes *bytes, const uint8_t *ptr, size_t size);
void
pb_bytes_set_ptr(struct pb_bytes *bytes, const uint8_t *ptr, size_t size);

DESCRIPTION
The pb_bytes functions manage struct pb_bytes, the in-memory representations of protobuf ‘bytes’ objects, which store a pointer and a size in bytes and represent arbitrary sequences of octets.

Callers should not create or manipulate struct pb_bytes objects directly; rather, they should obtain such objects only as parts of protobuf messages that have been initialized with pb_init(3).

Bytes may be stored either in static user-allocated buffers, or in buffers dynamically allocated by the enclosing protobuf message's allocator (see pb(3) about allocators). User-allocated buffers must be valid for the lifetime of the struct pb_bytes object.

The functions pb_bytes_alloc(), pb_bytes_set_copy(), and pb_bytes_set_ptr() free any previously dynamically allocated buffer and may change the allocation of the bytes. Destroying the enclosing protobuf message frees any dynamically allocated buffer.

FUNCTIONS

pb_bytes_size(bytes)
    Returns the number of bytes in bytes.

pb_bytes_ptr(bytes, sizep)
    Stores the size of bytes in *sizep and returns a pointer to that many bytes. If bytes is empty, the resulting pointer may not be used and may be NULL.

pb_bytes_ptr_mutable(bytes, sizep)
    Stores the size of bytes in *sizep and returns a non-const pointer to the buffer inside bytes, which must be dynamically allocated.

pb_bytes_alloc(bytes, size)
    Frees any previously dynamically allocated buffer in bytes and dynamically allocates a buffer for size bytes, which must be initialized by the caller by using pb_bytes_ptr_mutable.()

    Returns zero on success or ENOMEM if out of memory.

pb_bytes_set_copy(bytes, ptr, size)
    Frees any previously dynamically allocated buffer in bytes and dynamically allocates a buffer for size bytes, initialized from the size bytes in memory starting at ptr.

    Returns zero on success or ENOMEM if out of memory.

pb_bytes_set_ptr(bytes, ptr, size)
    Frees any previously dynamically allocated buffer in bytes and sets it to use the static user-allocated buffer of size bytes at ptr.

SEE ALSO
picopbc(1), errno(2), pb(3), pb_string(3)

AUTHORS
Taylor R Campbell <campbell+picopb@mumble.net>