NAME
hexall_fmt, hex_fmt - printf given text/data in hexadecimal
SYNOPSIS
#include <limb/hex.h>
int hexall_fmt(char *dst, size_t dlen, const char *sce, size_t slen, int options, size_t *w, size_t *r) ssize_t hex_fmt(char *dst, size_t dlen, const char *sce, size_t slen, int options)
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).