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

# NAME

hexall\_fmt, hex\_fmt - printf given text/data in hexadecimal

# SYNOPSIS

    #include <limb/hex.h>

```pre hl
int hexall_fmt(char *<em>dst</em>, size_t <em>dlen</em>, const char *<em>sce</em>, size_t <em>slen</em>, int <em>options</em>, size_t *<em>w</em>, size_t *<em>r</em>)
ssize_t hex_fmt(char *<em>dst</em>, size_t <em>dlen</em>, const char *<em>sce</em>, size_t <em>slen</em>, int <em>options</em>)
```

# DESCRIPTION

The `hexall_fmt`() function will write the content of `sce` of length `slen`
bytes, starting at offset pointed by `r` (usually 0), into the memory area
pointed by `dst` starting at position `w` (usually 0) and never going past
`dlen`, in hexadecimal form (each byte represented as 2 bytes in base16).

The values pointed to by `r` and `w` are updated accordingly to reflect the
positions of the last read in `sce` and write in `dst`, respectively.
Specifically, if a byte couldn't be written out for lack of space in `dst`, the
value pointed to by `r` would remain on the last successfully processed byte,
and no "partial write" would have occurred in `dst`.

If `dst` is *NULL* then nothing is written, the data in `sce` is still processed
and both `r` and `w` (/both/ mandatory) updated accordingly.

It is possible to define some options affecting the output written in `dst` via
the `options` argument, whose value is constructed as a bitwise-inclusive OR of
the following :

: *HEX_SP*
:: Add a space after each value (i.e. after the 2 bytes representing one byte in
: `sce`).

: *HEX_LF*
:: Add a newline (`\n`) at the end.

: *HEX_1BLOCK_SP*, *HEX_2BLOCK_SP*, *HEX_3BLOCK_SP*, *HEX_4BLOCK_SP*
:: Add a space after every one, two, three or four (respectively) blocks of
:: value have been written out.

: *HEX_1BLOCK_LF*, *HEX_2BLOCK_LF*, *HEX_3BLOCK_LF*, *HEX_4BLOCK_LF*
:: Add a newline (`\n`) after every one, two, three or four (respectively)
:: blocks of value have been written out.

When combining those, only one extra character can be written out at any given
position, except for the spaces added via *HEX_SP*.
Meaning that after e.g. 16 values have been written out, either one newline
/or/ one space will be added. For example, using `HEX_1BLOCK_SP | HEX_2BLOCK_SP
| HEX_2BLOCK_LF` would only result in a newline being added :
- Both *HEX_1BLOCK_SP* and *HEX_2BLOCK_SP* match the position, so only one
  space would be added, but
- When both spaces and newlines are a match, newlines take priority.

As indicated, spaces added due to *HEX_SP* are not affected, so 2 spaces could
be added after 8 values if using e.g. `HEX_SP | HEX_1BLOCK_SP`

Similarly two consecutive newlines will never be added, so using e.g. `HEX_LF |
HEX_4BLOCK_LF` on a 32 bytes block of data (`slen` = 32) would only lead to
a single newline added.

The `hex_fmt`() function is similar, only without the `r` and `w` arguments, and
different return values.

# RETURN VALUE

The `hexall_fmt`() function returns 1 on success. Otherwise it returns 0 and
sets `errno` to indicate the error.

In either case, values pointed to by `r` and `w` will have been updated to
reflect the positions of the last read in `sce` and write in `dst`,
respectively.

The `esc_fmt`() returns the number of bytes written into `dst` on success.
Otherwise it returns -1 and set `errno` to indicate the error.

# ERRORS

The `escall_fmt`() and `esc_fmt`() functions may fail if :

: *ENOBUFS*
:: Not enough space in `dst`.

The `escall_fmt`() function may also fail if :

: *EINVAL*
:: Either `r` or `w` was too high (more than `slen` or `dlen`, respectively).

# SEE ALSO

[buffer_puthex](3)