PB_STRING(3)

NAME
pb_string - protocol buffers string objects

LIBRARY
Protocol buffers library (libpicopb, -lpicopb)

SYNOPSIS
#include <pb.h>
size_t
pb_string_len(const struct pb_string *string);
const char *
pb_string_ptr(const struct pb_string *string);
char *
pb_string_ptr_mutable(const struct pb_string *string);
int
pb_string_alloc(struct pb_string *string, size_t len);
int
pb_string_set_copy(struct pb_string *string, const char *ptr, size_t len);
void
pb_string_set_ptr(struct pb_string *string, const char *ptr, size_t len);
int
pb_string_set_copy_asciz(struct pb_string *string, const char *ptr);
void
pb_string_set_ptr_asciz(struct pb_string *string, const char *ptr);
int
pb_utf8_validate(const uint8_t *buf, size_t len);

DESCRIPTION
The pb_string functions manage struct pb_string, the in-memory representations of protobuf ‘string’ objects, which store a pointer to a buffer in memory and a length in octets, and represent valid UTF-8 sequences.

The buffer in memory is guaranteed to be non-NULL and NUL-terminated, as a precaution against mistakes. However, valid UTF-8 sequences may include NUL octets, so a string does not necessarily end at the first one: you must use the stored length of the string instead.

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

Strings 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_string object.

The functions pb_string_alloc(), pb_string_set_copy(), pb_string_set_ptr(), pb_string_set_copy_asciz(), and pb_string_set_ptr_asciz() free any previously dynamically allocated buffer and may change the allocation of the string. Destroying the enclosing protobuf message frees any dynamically allocated buffer.

Although protobuf strings are expected to contain valid UTF-8 sequences, the functions do not validate their inputs to guarantee this. Validation is the responsibility of whoever stores data in strings. The pb_decode(3) functions validate input from the wire before storing it in strings. Users may use pb_utf8_validate() to validate on their own.

FUNCTIONS

pb_string_len(string)
    Returns the number of octets in string.

    This does not include the NUL terminator guaranteed to follow that number of octets in memory after the string's pointer. The expression
        pb_string_ptr(string)[pb_string_len(string)] == '\0'

    is guaranteed to be true as long as s is initialized.

pb_string_ptr(string)
    Returns the pointer to the buffer inside string. As long as string is initialized, this pointer is guaranteed to be non-NULL.

pb_string_ptr_mutable(string)
    Returns a non-const pointer to the buffer inside string, which must be dynamically allocated.

pb_string_alloc(string, len)
    Frees any previously dynamically allocated buffer in string and dynamically allocates a NUL-terminated buffer for len octets, which must be initialized by the caller through the pointer returned by pb_string_ptr_mutable().

    Returns zero on success or ENOMEM if out of memory.

pb_string_set_copy(string, ptr, len)
    Frees any previously dynamically allocated buffer in string and dynamically allocates a NUL-terminated buffer for len octets, initialized from the len octets in memory starting at ptr.

    Returns zero on success or ENOMEM if out of memory.

pb_string_set_ptr(string, ptr, len)
    Frees any previously dynamically allocated buffer in string and sets it to use the static user-allocated buffer of len octets at ptr. It is the user's responsibility to ensure that ptr[len] is a NUL octet.

pb_string_set_copy_asciz(string, ptr)
    Abbreviation for:

        pb_string_set_copy_asciz(string, ptr, strlen(ptr))

    The memory pointed to by ptr must be NUL-terminated.

    Returns zero on success or ENOMEM if out of memory.

pb_string_set_ptr_asciz(string, ptr)
    Abbreviation for

        pb_string_set_ptr_asciz(string, ptr, strlen(ptr))

    The memory pointed to by ptr must be NUL-terminated.

pb_utf8_validate(buf, len)
    Validates the sequence of len octets in buf as UTF-8. Returns zero if it is a valid UTF-8 sequence or EILSEQ if not.

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

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