NAME
buffer_putmsg - write message given as array of strings to a buffer
SYNOPSIS
#include <limb/buffer.h>
void buffer_putmsg(buffer *buf, const char * const *strings, unsigned int nstr)
DESCRIPTION
The buffer_putmsg() function will write the message, composed of nstr
NUL-terminated strings from array strings, into buffer buf.
Note that it is allowed to give NULL as a string, in which case it will be treated as an empty string (i.e. nothing is added to the buffer).
Special "strings"
A few constants are defined that can be given as one strings in the array
strings, to have special meaning.
When PUTMSG_FLUSH was given as one of the string, the buffer is immediately flushed. Nothing is added to the buffer in its place, and processing continues on with remaining strings afterwards.
When PUTMSG_TOGGLE_ESC was given as one of the strings, escaping mode is toggled. See ESCAPING below for more.
When PUTMSG_ESC (or ESC) was given as one of the strings, escaping mode is toggled (See ESCAPING below for more) and a double-quote is added.
When PUTMSG_UINT_NEXT was given as one of the strings, it acts as an indicator
that the next element in strings should be treated as an unsigned integer
(instead of a pointer to a string) whose value should be written in decimal form
into the buffer.
When PUTMSG_INT_NEXT was given as one of the strings, it does the same as PUTMSG_UINT_NEXT only treating the next element as a signed integer.
When PUTMSG_ERR_NEXT was given as one of the strings, in its place is put the error description of the error, as returned by strerror(3), whose value is to be obtained from the following element, treated as an unsigned integer (instead of a pointer to a string).
When PUTMSG_LEN_NEXT was given as one of the strings, it acts as an indicator
that the next element in strings is a string that may not be NUL-terminated,
and whose length to be written into buf is to be obtained for the following
element, treated as an unsigned integer (instead of a pointer to a string).
When PUTMSG_HEX_NEXT was given as one of the strings, it acts as an indicator
that the next element in strings is a byte-array whose length in to be
obtained from the following element, treated as an unsigned integer (instead of
a pointer to a string).
The content of the byte array shall be written into the buffer as an hexadecimal
dump, as described on buffer_puthex(3).
When PUTMSG_DUMP_NEXT was given as one of the strings, it acts similarly to
when PUTMSG_HEX_NEXT is given, only with options HEX_SP | HEX_1BLOCK_SP | HEX_3BLOCK_LF | HEX_LF given to buffer_puthex(3), so a space is added after
each byte, another space after every 8 bytes, a newline after every 24 bytes,
and a trailing new line is added.
A few macros are available, in order to simply things:
PUTMSG_ASUINT(n), PUTMSG_ASINT(n)
To cast n as unsigned or signed integer, respectively, to be added into
a string array.
PUTMSG_UINT(n), PMUINT(n)
Shorthand to easily add an unsigned number into a message. This is
intended for use in a coma-separated list, as it expands to :
PUTMSG_UINT_NEXT, PUTMSG_ASUINT(n)
PUTMSG_INT(n), PMINT(n)
Shorthand to easily add a signed number into a message. This is intended
for use in a coma-separated list, as it expands to :
PUTMSG_INT_NEXT, PUTMSG_ASINT(n)
PUTMSG_ERR(n), PMERR(n)
Shorthand to easily add an error description. This is intended for use in a
coma-separated list, as it expends to :
PUTMSG_ERR_NEXT, PUTMSG_ASUINT(n)
PUTMSG_LEN(data, dlen), PMLEN(data, dlen)
Shorthand to easily write (part of) a string that's not NUL terminated This
is intended for use in a coma-separated list, as it expands to:
PUTMSG_LEN_NEXT, data, PUTMSG_ASUINT(dlen)
PUTMSG_HEX(data,dlen), PMHEX(data,dlen)
Shorthand to easily add a blob/byte array whose content shall be written
out in hexadecimal form into a message. This is intended for use in a
coma-separated, as it expands to:
PUTMSG_HEX_NEXT, data, PUTMSG_ASUINT(dlen)
PUTMSG_DUMP(data, dlen), PMDUMP(data, dlen)
Shorthand to easily add an hexadecimal dump of a data blob/byte array. This
is intended for use in a coma-separated list, as it expands to:
PUTMSG_DUMP_NEXT, data, PUTMSG_ASUINT(dlen)
ESCAPING
It is possible to pass the special constant PUTMSG_TOGGLE_ESC or PUTMSG_ESC (or ESC) as one of the strings, so that following strings will be escaped using buffer_putesc(3). It can be specified again to stop escaping and return to "normal" processing.
PUTMSG_TOGGLE_ESC only has for effect to toggle the escaping, while
PUTMSG_ESC and ESC will also have a double quote (") will be put in place
of each constant.
This escaping can be enabled as many times as needed.
EXAMPLES
To write into a buffer a message containing a number one could use the following :
1 2 3
cint r = 42;
const char *strings[] = { "The answer is ", PUTMSG_UINT_NEXT, PUTMSG_ASUINT(r), "\n", PUTMSG_FLUSH };
buffer_putmsg(buffer_1, strings, sizeof(strings) / sizeof(*strings));
Which is identical to the following :
1 2 3
cint r = 42;
const char *strings[] = { "The answer is ", PUTMSG_UINT(r), "\n", PUTMSG_FLUSH };
buffer_putmsg(buffer_1, strings, 5);