% limb manual
% buffer_putmsg(3)
% limb 0.1.0
% 2023-07-24

# NAME

buffer\_putmsg - write message given as array of strings to a buffer

# SYNOPSIS

    #include <limb/buffer.h>

```pre hl
void buffer_putmsg(buffer *<em>buf</em>, const char * const *<em>strings</em>, unsigned int <em>nstr</em>)
```

# 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.

! INFO:
! 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 :

```c
int 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 :

```c
int r = 42;
const char *strings[] = { "The answer is ", PUTMSG_UINT(r), "\n", PUTMSG_FLUSH };
buffer_putmsg(buffer_1, strings, 5);
```