\" $NetBSD: snprintb.3,v 1.39 2024/04/08 21:28:35 rillig Exp $

\" $NetBSD: snprintb.3,v 1.39 2024/04/08 21:28:35 rillig Exp $
\"
\" Copyright (c) 1998, 2024 The NetBSD Foundation, Inc.
\" All rights reserved.
\"
\" This code is derived from software contributed to The NetBSD Foundation
\" by Jeremy Cooper.
\"
\" Redistribution and use in source and binary forms, with or without
\" modification, are permitted provided that the following conditions
\" are met:
\" 1. Redistributions of source code must retain the above copyright
\" notice, this list of conditions and the following disclaimer.
\" 2. Redistributions in binary form must reproduce the above copyright
\" notice, this list of conditions and the following disclaimer in the
\" documentation and/or other materials provided with the distribution.
\"
\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
\" POSSIBILITY OF SUCH DAMAGE.
\"
Dd April 8, 2024
Dt SNPRINTB 3
Os
Sh NAME
Nm snprintb ,
Nm snprintb_m
Nd bitmask output conversion
Sh LIBRARY
Lb libutil
Sh SYNOPSIS
In util.h
Ft int
Fn "snprintb" "char *buf" "size_t bufsize" "const char *fmt" "uint64_t val"
Ft int
Fn "snprintb_m" "char *buf" "size_t bufsize" "const char *fmt" "uint64_t val" \
"size_t max"
Sh DESCRIPTION
The
Fn snprintb
function formats a bitmask into a mnemonic form suitable for printing.
Pp
It formats the integer
Fa val
into the buffer
Fa buf ,
of size
Fa bufsize ,
interpreting the bits within that integer as flags or groups of bits.
The buffer is always
Tn NUL Ns -terminated.
If the buffer
Fa buf
is too small to hold the formatted output,
Fn snprintb
will fill as much as it can, and return the number of bytes
that it would have written if the buffer were long enough excluding the
terminating
Tn NUL .
If
Fa bufsize
is zero, nothing is written and
Fa buf
may be a null pointer.
Pp
The
Fn snprintb_m
function accepts an additional
Fa max
argument.
If this argument is zero, the
Fn snprintb_m
function behaves exactly like the
Fn snprintb
function.
If the
Fa max
argument has a non-zero value, it represents the maximum length of a
formatted string.
If the formatted string would require more than
Fa max
characters, the
Fn snprintb_m
function returns multiple formatted strings in the output buffer
Fa buf .
Each string is
Tn NUL Ns -terminated ,
and the last string is followed by an
additional
Tn NUL
character
Pq or, if you prefer, a zero-length string .
Pp
The decoding directive in
Fa fmt
describes how the bitfield is to be interpreted and displayed.
It follows two possible formats, referred to as
Dq old
and
Dq new .
The
Dq old
format is limited to describing single bits in a 32-bit value,
the bit positions are 1-based.
The
Dq new
format supports multi-bit fields and 64-bit values,
the bit positions are 0-based.
Pp
If the first character of
Fa fmt
is
Pq in C escape-character format
Ql \e177
or
Ql \ex7f ,
the remainder of the
Fa fmt
argument follows the
Dq new
format.
Pp
The next character
Po the first for the
Dq old
format
Pc
specifies the numeral base in which to print the numbers in the output.
The possible values are
Ql \e010
or
Ql \ex08
for octal,
Ql \e012
or
Ql \ex0a
for decimal, and
Ql \e020
or
Ql \ex10
for hexadecimal.
Pp
The remaining characters in the
Fa fmt
argument represent the formatting conversions,
according to the
Dq old
or
Dq new
format.