libutil/snprintb: allow 'f' to be combined with ':'

But only if the numeric value can be clearly distinguished from the
description. This style is used by sh3/dmacreg.h.

snprintb.3: provide examples for hexadecimal character escapes

Suggested by uwe@, in reaction to the previous commit, which preferred
octal in the examples. Hexadecimal escapes are more familiar to most
programmers, and the chance of mistaking \x14 for decimal 14 is less
than the chance of mistaking octal \014 for decimal 14.

snprintb.3: clean up formatting and wording, prefer octal in examples

Using hexadecimal character escapes requires separate string literals if
the description starts with one of the letters A-F; octal character
escapes have at most 3 digits, reducing ambiguity.

snprintb: reject combinations of 'f' with ':' as well as 'F' with '='

These combinations would lead to garbled output.

snprintb.3: fix typo

snprintb: always null-terminate output

Always null-terminate the output in the buffer, even in error cases. The
wording in the manual page has been promising this since 2008. For
snprintb_m, ensure that the output is terminated with two null
characters, to gracefully handle situations in which the caller does not
check whether snprintb returned an error.

If the buffer size is zero, allow the buffer to be a null pointer,
analogous to snprintf.

Fix an out-of-bounds memory read if the bitfmt ends with a '*' directive
(since today).

In the tests, merge the helper functions for snprintb, snprintb_m, as
they were similar enough.

Fix a few 'line_max exceeded' tests, ensuring that they output a '#'
marker, and that the 'complete' tests don't.

snprintb: error out on out-of-bounds bit shifts

Previously, these invoked undefined behavior, now they lead to an early
return. An example of out-of-bounds bit number is in SCZ_PCICTRL_BITS.
Bit fields that extend beyond the msb are still allowed.

Allow 'f' and 'F' to have fields that are 64 bits wide. This only makes
sense when the field starts at bit 0.

Remove the unused 'val_len', it was only needed before snprintb.c 1.20.

snprintb.3: sync examples with reality

mman.h: fix snprintb description for alignment 2^60

snprintb: rename buflen to bufsize, following the wording in snprintf

snprintb.3: fix examples, clean up wording

In the examples using hex escape sequences, there must be a delimiter
between the escape sequence and the following description if the
description starts with [A-Fa-f], as hex escape sequences are not
limited in length.

Distinguish between a 'directive' (bit + length + description) and a
'description' (only the text).

The fmt parameter is not a string, as strings only reach to the first
'\0' byte, but the new-style format may include additional '\0' as bit
numbers.

snprintb(3): restore empty string in snprintb_m example

Restore the empty string at the end of snprintb_m output that was
accidentally removed along with empty string placeholders in the
format strings. While here, move that example to be next to its
snprintb counterpart.

snprintb(3): update mmap example

Bring over the prettier version of the mmap format string that we have
in the header file for some time now. Clarify that the final NUL of
the new format string is supplied by the compiler, g/c explicit final
\0 from the example that had it.

snprintb(3): try to improve narration

Try to make the narration more coherent. Make the old and new
syntaxes easy to distinguish and go out of our way to highlight that
the old syntax uses 1-based bit positions.

snprintb.3: remove empty string literals from examples

Suggested by uwe@, as gaps in bitmasks are quite common and thus
shouldn't clutter the code.

snprintb.3: fix examples

The first example broke the format string at boundaries that didn't
highlight the structure of the format string and also didn't make it
clear that a few bits were omitted from having descriptions.

The second example contained an off-by-one error for SIXTEEN, which was
actually FIFTEEN.

The snprintb_m example repeated the above off-by-one error, and its
output was shown wrong, due to concatenated escape sequences.

Fix grammar.

Remove trailing whitespace.

Correct the man page, and say that the printf(3) format characters need
to be uintmax_t.

snprintb(3) says that, in the new(?) Torek format, all fields specs end with \0
The F spec is one of those, it should be terminated with \0 just like all
the others (irrelevant that it has no extra data to delimit).

Fix <sys/mman.h> to define the snprintb() format string correctly (include
the missing \0's). Fix the copy of that definition included into
snprintb(3) to match the updated mman.h version (ride the date bump
from the day before yesterday .. this is the same change, just corrected).

Undo the previous snprintb.c change ("off by one" fix) which was an
attempt to make the broken mman.h usage work (and did, but not the way
it should be done). Also, after using the new * format (instead of only
when something has already matched) skip the associated data so we don't
attempt to interpret it as more field specifiers. This func needs lots of TLC!

Fix the ATF tests for snprintb() to not assume that F format is really
exactly like f format, and has data after the field specifier. It doesn't.
Add several more tests (including testing the '*' field operator
recently added).

Remove trailing whitespace.

remove dup line

Document the '*' field and give a more complex example with F and *.

branches: 1.17.4;
Add snprintb_m to the NAME section.

Update example using hex-escape-sequences to conform to gcc parsing rules.
(See http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33167 for details.)

Add an example using snprintb_m()

Replace \*[Gt] and \*[Lt] with the simple characters > and < (OK wiz)

XXX Note that the examples currently do not compile with GCC! The hex
XXX character sequences such as \x10CACHE are being parsed as longer
XXX than 2-hex-digit strings!

branches: 1.14.6; 1.14.12;
Implement snprintb_m(3) to provide multi-line bit/bit-field decode.
Discussed on tech-kern.

Update type of argument 4 from u_quad_t to uint64_t to match the actual
implementation.

Correct the order of arguments in EXAMPLE. Bump date.

branches: 1.11.2; 1.11.4;
Fix deleto in previous.

fix argument order in example.

Re-add LIBRARY section.

Fix some minor mdoclint complaints.

use the bitmask_snprintf info which is more complete, and adjust it for
reality.

Convert TNF licenses to new 2 clause variant

branches: 1.5.24;
Add missing LIBRARY section.

ok wiz@

fix the header.

Use
.In header.h
instead of
.Fd #include \*[Lt]header.h\*[Gt]
Much easier to read and write, and supported by groff for ages.
Okayed by ross.

New sentence, new line. From Robert Elz.

Add snprintb(3) inspired from bitmask_snprintf(9), but made to look like
more like snprintf(3). Discussed with thorpej.