>Number:         19559
>Category:       kern
>Synopsis:       bitmask_snprintf(9) does not document extended format
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    kern-bug-people
>State:          open
>Class:          sw-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Dec 25 00:28:00 PST 2002
>Closed-Date:
>Last-Modified:
>Originator:     Ron Roskens
>Release:        1.6
>Organization:
>Environment:
>Description:
The man page for bitmask_snprintf(9) says its a bug that the new extended format is not described in the man page.

Also, the man page makes refernce to bit 32 being the most significant bit which is not true since val is a u_quad_t of 64 bits.
>How-To-Repeat:
man bitmask_snprintf
>Fix:
Change references to MSB from 32 to 64.

Add an example of the new format:

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

If the first character in fmt is '\177', then the extended format is used and the second character is the output numeral base. Sequences of NULL (\0) terminated strings are used until the decoding directive string is finished. The sequences begin with either a 'b', 'f' or 'F'.

When a 'b' character is used, a bit-position-description pair follows terminated by a '\0'. This format is the same as the old-style.

When a 'f' character is used, a bit-position-fieldlength-description tuple follows terminated by a '\0'. The bit-position and bit-field-length are single byte values, followed by a character string describing the bit-field. The output buffer will display the character string '=' bit-field-value. [ie: FIELD2=b ]

When an 'F' is used, '\0' terminated tuple is lengthened for a comparision case. Following the bit-position-fieldlength of the 'f' format is either an '=' or ':' character, a bit-field-value and a character string describing the bit-field. The string will only be displayed if bit-field-value is equal to the value corresponding to bit-field in val. When this format uses an '=' instead of a ':', the character string is preceded by an '=' in the output buffer.

bitmask_snprintf(ad, "\177\20" "b\0BITZERO\0b\1BITONE\0"
                     "f\2\4FIELD2\0" "F\6\2=\2FIELD7\0\0",
                 buf, buflen)
           => "ad=<BITZERO,FIELD2=b,=FIELD7>"


>Release-Note:
>Audit-Trail:
>Unformatted: