PB(3)

NAME
pb, libpicopb - protocol buffers run-time support library

LIBRARY
Protocol buffers library (libpicopb, -lpicopb)

SYNOPSIS
#include <pb.h>
void
pb_init(struct pb_msg msg);
void
pb_allocator_init(const struct pb_allocator *allocator, struct pb_msg msg);
void
pb_destroy(struct pb_msg msg);

DESCRIPTION
The pb library is the run-time support library for handling protocol buffers, or protobuf for short, using the output of picopbc(1).

Structures for protobuf messages must be initialized with the pb_init() or pb_allocator_init() functions before use, and destroyed with pb_destroy() when done, if they were not obtained as submessages of an existing message.

In order to ensure type safety, for a protobuf message Msg with a corresponding C structure struct Msg m, there is a function Msg() which is called as Msg(&m) and returns a struct pb_msg containing both &m and a pointer to the run-time data necessary to describe Msg to pb. Thus, the C compiler will detect attempts to initialize messages with the wrong types, such as pb_init(Nsg(&m)).

To encode protobuf messages to send over the wire, use pb_encode(3). To decode protobuf messages received over the wire, use pb_decode(3).

FUNCTIONS

pb_init(msg)
    Initialize the message structure pointed to by msg, as returned by the struct pb_msg constructor defined for a protobuf message. This must be called before any attempt to use the message structure.

pb_allocator_init(allocator, msg)
    Initialize msg with the specified allocator. All memory allocated for the resulting message, such as strings or repeated submessages, will be obtained via allocator.

pb_destroy(msg)
    Free any memory associated with the message structure pointed to by msg.

ALLOCATORS
The pb library may use dynamically allocated memory provided by an allocator described in the following structure:

    struct pb_allocator {
            void    *(*pba_alloc)(size_t);
            void    *(*pba_realloc)(void *, size_t, size_t)
            void    (*pba_free)(void *, size_t);
    };

There is a default allocator provided by the library, but users wishing to use a custom allocator may do so by providing the following functions:

pba_alloc(n)
    Must return a pointer to n bytes of freshly allocated memory, or NULL if out of memory.

    The size n is guaranteed not to be zero.

pba_realloc(p, osize, nsize)
    Must return a pointer to nsize bytes of memory sharing the first osize or nsize bytes of memory at p, whichever is smaller; or return NULL if out of memory. The pointer p will have been allocated with osize bytes by a call to pba_alloc() or by another call to pba_realloc(). pba_realloc() may return p, or may free the memory pointed to by p and return a pointer to elsewhere in memory. The pointer p is guaranteed not to be NULL, and the sizes osize and nsize are guaranteed not to be zero.

pba_free(p, n)
    Must free the memory pointed to by p, which will have been allocated with n bytes by a call to pba_alloc() or pba_realloc().

    The pointer p is guaranteed not to be NULL, and the size n is guaranteed not to be zero.

SEE ALSO
picopbc(1), pb_bytes(3), pb_decode(3), pb_encode(3), pb_repeated(3), pb_string(3)

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