1.\" $NetBSD: snprintb.3,v 1.11 2008/12/23 21:46:13 wiz Exp $ 2.\" 3.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jeremy Cooper. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd December 23, 2008 31.Dt SNPRINTB 3 32.Os 33.Sh NAME 34.Nm snprintb 35.Nd bitmask output conversion 36.Sh LIBRARY 37.Lb libutil 38.Sh SYNOPSIS 39.In util.h 40.Ft int 41.Fn "snprintb" "char *buf" "size_t buflen" "const char *fmt" "u_quad_t val" 42.Sh DESCRIPTION 43The 44.Fn snprintb 45function formats a bitmask into a mnemonic form suitable for printing. 46.Pp 47This conversion is useful for decoding bit fields in device registers. 48It formats the integer 49.Fa val 50into the buffer 51.Fa buf , 52of size 53.Fa buflen , 54using a specified radix and an interpretation of 55the bits within that integer as though they were flags. 56The buffer is always NUL-terminated. 57If the buffer 58.Fa buf 59is too small to hold the formatted output, 60.Fn snprintb 61will fill as much as it can, and return the number of bytes 62that would have written if the buffer was long enough excluding the 63terminating NUL. 64.Pp 65The decoding directive string 66.Fa fmt 67describes how the bitfield is to be interpreted and displayed. 68It follows two possible syntaxes, referred to as 69.Dq old 70and 71.Dq new . 72The main advantage of the 73.Dq new 74formatting is that it is capable of handling multi-bit fields. 75.Pp 76The first character of 77.Fa fmt 78may be 79.Li \e177 , 80indicating that the remainder of the format string follows the 81.Dq new 82syntax. 83The second character 84.Pq the first for the old format 85is a binary character representation of the 86output numeral base in which the bitfield will be printed before it is decoded. 87Recognized radix values 88.Pq in C escape-character format 89are 90.Li \e10 91.Pq octal , 92.Li \e12 93.Pq decimal , 94and 95.Li \e20 96.Pq hexadecimal . 97.Pp 98The remaining characters in 99.Fa fmt 100are interpreted as a list of bit-position\(endescription pairs. 101From here the syntaxes diverge. 102.Pp 103The 104.Dq old 105format syntax is series of bit-position\(endescription pairs. 106Each begins with a binary character value that represents the position 107of the bit being described. 108A bit position value of one describes the least significant bit. 109Whereas a position value of 32 110.Pq octal 40, hexadecimal 20, the ASCII space character 111describes the most significant bit. 112.Pp 113The remaining characters in a bit-position\(endescription pair are the 114characters to print should the bit being described be set. 115Description strings are delimited by the next bit position value character 116encountered 117.Pq distinguishable by its value being \*[Le] 32 , 118or the end of the decoding directive string itself. 119.Pp 120For the 121.Dq new 122format syntax, a bit-position\(endescription begins with a field type 123followed by a binary bit-position and possibly a field length. 124The least significant bit is bit-position zero, unlike the 125.Dq old 126syntax where it is one. 127.Bl -tag -width "xxxxx" 128.It Cm b\eB 129Describes a bit position. 130The bit-position 131.Fa B 132indicates the corresponding bit, as in the 133.Dq old 134format. 135.It Cm f\eB\eL 136Describes a multi-bit field beginning at bit-position 137.Fa B 138and having a bit-length of 139.Fa L . 140The remaining characters are printed as a description of the field 141followed by 142.Sq \&= 143and the value of the field. 144The value of the field is printed in the base specified as the second 145character of the decoding directive string 146.Ar fmt . 147.It Cm F\eB\eL 148Describes a multi-bit field like 149.Sq f , 150but just extracts the value for use with the 151.Sq \&= 152and 153.Sq \&: 154formatting directives described below. 155.It Cm \&=\eV 156The field previously extracted by the last 157.Sq f 158or 159.Sq F 160operator is compared to the byte 161.Sq Cm V 162.Pq for values 0 through 255 . 163If they are equal, 164.Sq \&= 165followed by the string following 166.Sq Cm V 167is printed. 168This and the 169.Sq \&: 170operator may be repeated to annotate multiple possible values. 171.It Cm :\eV 172Operates like the 173.Sq \&= 174operator, but omits the leading 175.Sq \&= . 176.El 177.Pp 178Finally, each field is delimited by a NUL 179.Pq Sq \e0 180character. 181By convention, the format string has an additional NUL character at 182the end, following that delimiting the last bit-position\(endescription 183pair. 184.Sh RETURN VALUES 185The 186.Fn snprintb 187function returns the number of bytes that would have written to the buffer 188if there was adequate space, excluding the terminating NUL, or \-1 in case 189an error occurred. 190.Sh EXAMPLES 191Two examples of the old formatting style: 192.Bd -literal -offset indent 193snprintb(buf, buflen, 3, "\e10\e2BITTWO\e1BITONE") 194\(rA "3\*[Lt]BITTWO,BITONE\*[Gt]" 195 196snprintb(buf, buflen, 0xe860, 197 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 198 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 199 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE") 200\(rA "e860\*[Lt]NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE\*[Gt]" 201.Ed 202.Pp 203An example of the new formatting style: 204.Bd -literal -offset indent 205snprintb(buf, buflen, 0x800f0701, 206 "\e177\e020b\e0LSB\e0b\e1_BITONE\e0f\e4\e4NIBBLE2\e0" 207 "f\ex10\e4BURST\e0=\e4FOUR\e0=\exfSIXTEEN\e0" 208 "b\ex1fMSB\e0\e0") 209\(rA "800f0701\*[Lt]LSB,NIBBLE2=0,BURST=f=SIXTEEN,MSB\*[Gt]" 210.Ed 211.Sh ERRORS 212.Fn snprintb 213will fail if: 214.Bl -tag -width Er 215.It Bq Er EINVAL 216The leading character does not describe a supported format, 217or 218.Fn snprintf 219failed. 220.El 221.Sh SEE ALSO 222.Xr printf 3 , 223.Xr snprintf 3 224.Sh HISTORY 225The 226.Fn snprintb 227function was originally implemented as a non-standard 228.Li %b 229format string for the kernel 230.Fn printf 231function in 232.Nx 1.5 233and earlier releases. 234It was called 235.Fn bitmask_snprintf 236in 237.Nx 5.0 238and earlier releases. 239.Sh AUTHORS 240The 241.Dq new 242format was the invention of 243.An Chris Torek . 244