👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for snprintb (netbsd section 3)

SNPRINTB(3)			   BSD Library Functions Manual 		      SNPRINTB(3)

NAME
     snprintb -- bitmask output conversion

LIBRARY
     System Utilities Library (libutil, -lutil)

SYNOPSIS
     #include <util.h>

     int
     snprintb(char *buf, size_t buflen, const char *fmt, uint64_t val);

     int
     snprintb_m(char *buf, size_t buflen, const char *fmt, uint64_t val, size_t max);

DESCRIPTION
     The snprintb() function formats a bitmask into a mnemonic form suitable for printing.

     This conversion is useful for decoding bit fields in device registers.  It formats the inte-
     ger val into the buffer buf, of size buflen, using a specified radix and an interpretation
     of the bits within that integer as though they were flags.  The buffer is always NUL-termi-
     nated.  If the buffer buf is too small to hold the formatted output, snprintb() will fill as
     much as it can, and return the number of bytes that would have written if the buffer was
     long enough excluding the terminating NUL.

     The decoding directive string fmt describes how the bitfield is to be interpreted and dis-
     played.  It follows two possible syntaxes, referred to as ``old'' and ``new''.  The main
     advantage of the ``new'' formatting is that it is capable of handling multi-bit fields.

     The first character of fmt may be \177, indicating that the remainder of the format string
     follows the ``new'' syntax.  The second character (the first for the old format) is a binary
     character representation of the output numeral base in which the bitfield will be printed
     before it is decoded.  Recognized radix values (in C escape-character format) are \10
     (octal), \12 (decimal), and \20 (hexadecimal).

     The remaining characters in fmt are interpreted as a list of bit-position-description pairs.
     From here the syntaxes diverge.

     The ``old'' format syntax is series of bit-position-description pairs.  Each begins with a
     binary character value that represents the position of the bit being described.  A bit posi-
     tion value of one describes the least significant bit.  Whereas a position value of 32
     (octal 40, hexadecimal 20, the ASCII space character) describes the most significant bit.

     The remaining characters in a bit-position-description pair are the characters to print
     should the bit being described be set.  Description strings are delimited by the next bit
     position value character encountered (distinguishable by its value being <= 32), or the end
     of the decoding directive string itself.

     For the ``new'' format syntax, a bit-position-description begins with a field type followed
     by a binary bit-position and possibly a field length.  The least significant bit is bit-
     position zero, unlike the ``old'' syntax where it is one.

     b\B    Describes a bit position.  The bit-position B indicates the corresponding bit, as in
	    the ``old'' format.

     f\B\L  Describes a multi-bit field beginning at bit-position B and having a bit-length of L.
	    The remaining characters are printed as a description of the field followed by '='
	    and the value of the field.  The value of the field is printed in the base specified
	    as the second character of the decoding directive string fmt.

     F\B\L  Describes a multi-bit field like 'f', but just extracts the value for use with the
	    '=' and ':' formatting directives described below.

     =\V    The field previously extracted by the last 'f' or 'F' operator is compared to the
	    byte 'V' (for values 0 through 255).  If they are equal, '=' followed by the string
	    following 'V' is printed.  This and the ':' operator may be repeated to annotate mul-
	    tiple possible values.

     :\V    Operates like the '=' operator, but omits the leading '='.

     Finally, each field is delimited by a NUL ('\0') character.  By convention, the format
     string has an additional NUL character at the end, following that delimiting the last bit-
     position-description pair.

     The snprintb_m() function accepts an additional max argument.  If this argument is zero, the
     snprintb_m() function returns exactly the same results in the buf as the snprintb() func-
     tion.  If the max argument is present and has a non-zero value, it represents the maximum
     length of a formatted string.  If the formatted string would require more than max charac-
     ters, the snprintb_m() function returns multiple formatted strings in the output buffer buf.
     Each string is NUL-terminated, and the last string is followed by an additional NUL charac-
     ter (or, if you prefer, a zero-length string).

RETURN VALUES
     The snprintb() and snprintb_m() functions return the number of bytes that would have written
     to the buffer if there was adequate space, excluding the final terminating NUL, or -1 in
     case an error occurred.  For snprintb_m(), the NUL characters terminating each individual
     string are included in the total number of bytes.

EXAMPLES
     Two examples of the old formatting style:

	   snprintb(buf, buflen, "\10\2BITTWO\1BITONE", 3)
	   => "3<BITTWO,BITONE>"

	   snprintb(buf, buflen,
		  "\20\x10NOTBOOT\x0fFPP\x0eSDVMA\x0cVIDEO"
		  "\x0bLORES\x0aFPA\x09DIAG\x07CACHE"
		  "\x06IOCACHE\x05LOOPBACK\x04DBGCACHE",
		  0xe860)
	   => "e860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>"

     An example of the new formatting style:

	   snprintb(buf, buflen,
		  "\177\020b\0LSB\0b\1_BITONE\0f\4\4NIBBLE2\0"
		  "f\x10\4BURST\0=\4FOUR\0=\xfSIXTEEN\0"
		  "b\x1fMSB\0\0",
		  0x800f0701)
	   => "800f0701<LSB,NIBBLE2=0,BURST=f=SIXTEEN,MSB>"

ERRORS
     snprintb() will fail if:

     [EINVAL]		The leading character does not describe a supported format, or snprintf()
			failed.

SEE ALSO
     printf(3), snprintf(3)

HISTORY
     The snprintb() function was originally implemented as a non-standard %b format string for
     the kernel printf() function in NetBSD 1.5 and earlier releases.  It was called
     bitmask_snprintf() in NetBSD 5.0 and earlier releases.

AUTHORS
     The ``new'' format was the invention of Chris Torek.

BSD					   May 7, 2009					      BSD


All times are GMT -4. The time now is 10:38 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?