1.\" $NetBSD: snprintb.3,v 1.16 2013/08/07 23:22:28 pgoyette 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 May 7, 2009 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" "uint64_t val" 42.Ft int 43.Fn "snprintb_m" "char *buf" "size_t buflen" "const char *fmt" "uint64_t val" \ 44"size_t max" 45.Sh DESCRIPTION 46The 47.Fn snprintb 48function formats a bitmask into a mnemonic form suitable for printing. 49.Pp 50This conversion is useful for decoding bit fields in device registers. 51It formats the integer 52.Fa val 53into the buffer 54.Fa buf , 55of size 56.Fa buflen , 57using a specified radix and an interpretation of 58the bits within that integer as though they were flags. 59The buffer is always NUL-terminated. 60If the buffer 61.Fa buf 62is too small to hold the formatted output, 63.Fn snprintb 64will fill as much as it can, and return the number of bytes 65that would have written if the buffer was long enough excluding the 66terminating NUL. 67.Pp 68The decoding directive string 69.Fa fmt 70describes how the bitfield is to be interpreted and displayed. 71It follows two possible syntaxes, referred to as 72.Dq old 73and 74.Dq new . 75The main advantage of the 76.Dq new 77formatting is that it is capable of handling multi-bit fields. 78.Pp 79The first character of 80.Fa fmt 81may be 82.Li \e177 , 83indicating that the remainder of the format string follows the 84.Dq new 85syntax. 86The second character 87.Pq the first for the old format 88is a binary character representation of the 89output numeral base in which the bitfield will be printed before it is decoded. 90Recognized radix values 91.Pq in C escape-character format 92are 93.Li \e10 94.Pq octal , 95.Li \e12 96.Pq decimal , 97and 98.Li \e20 99.Pq hexadecimal . 100.Pp 101The remaining characters in 102.Fa fmt 103are interpreted as a list of bit-position\(endescription pairs. 104From here the syntaxes diverge. 105.Pp 106The 107.Dq old 108format syntax is series of bit-position\(endescription pairs. 109Each begins with a binary character value that represents the position 110of the bit being described. 111A bit position value of one describes the least significant bit. 112Whereas a position value of 32 113.Pq octal 40, hexadecimal 20, the ASCII space character 114describes the most significant bit. 115.Pp 116The remaining characters in a bit-position\(endescription pair are the 117characters to print should the bit being described be set. 118Description strings are delimited by the next bit position value character 119encountered 120.Pq distinguishable by its value being \*[Le] 32 , 121or the end of the decoding directive string itself. 122.Pp 123For the 124.Dq new 125format syntax, a bit-position\(endescription begins with a field type 126followed by a binary bit-position and possibly a field length. 127The least significant bit is bit-position zero, unlike the 128.Dq old 129syntax where it is one. 130.Bl -tag -width "xxxxx" 131.It Cm b\eB 132Describes a bit position. 133The bit-position 134.Fa B 135indicates the corresponding bit, as in the 136.Dq old 137format. 138.It Cm f\eB\eL 139Describes a multi-bit field beginning at bit-position 140.Fa B 141and having a bit-length of 142.Fa L . 143The remaining characters are printed as a description of the field 144followed by 145.Sq \&= 146and the value of the field. 147The value of the field is printed in the base specified as the second 148character of the decoding directive string 149.Ar fmt . 150.It Cm F\eB\eL 151Describes a multi-bit field like 152.Sq f , 153but just extracts the value for use with the 154.Sq \&= 155and 156.Sq \&: 157formatting directives described below. 158.It Cm \&=\eV 159The field previously extracted by the last 160.Sq f 161or 162.Sq F 163operator is compared to the byte 164.Sq Cm V 165.Pq for values 0 through 255 . 166If they are equal, 167.Sq \&= 168followed by the string following 169.Sq Cm V 170is printed. 171This and the 172.Sq \&: 173operator may be repeated to annotate multiple possible values. 174.It Cm :\eV 175Operates like the 176.Sq \&= 177operator, but omits the leading 178.Sq \&= . 179.El 180.Pp 181Finally, each field is delimited by a NUL 182.Pq Sq \e0 183character. 184By convention, the format string has an additional NUL character at 185the end, following that delimiting the last bit-position\(endescription 186pair. 187.Pp 188The 189.Fn snprintb_m 190function accepts an additional 191.Fa max 192argument. 193If this argument is zero, the 194.Fn snprintb_m 195function returns exactly the same results in the 196.Fa buf 197as the 198.Fn snprintb 199function. 200If the 201.Fa max 202argument is present and has a non-zero value, it represents the maximum 203length of a formatted string. 204If the formatted string would require more than 205.Fa max 206characters, the 207.Fn snprintb_m 208function returns multiple formatted strings in the output buffer 209.Fa buf . 210Each string is NUL-terminated, and the last string is followed by an 211additional NUL character (or, if you prefer, a zero-length string). 212.Sh RETURN VALUES 213The 214.Fn snprintb 215and 216.Fn snprintb_m 217functions return the number of bytes that would have written to the buffer 218if there was adequate space, excluding the final terminating NUL, or \-1 in 219case an error occurred. 220For 221.Fn snprintb_m , 222the NUL characters terminating each individual string are included in the 223total number of bytes. 224.Sh EXAMPLES 225Two examples of the old formatting style: 226.Bd -literal -offset indent 227snprintb(buf, buflen, "\e10\e2BITTWO\e1BITONE", 3) 228\(rA "03<BITTWO,BITONE>" 229 230snprintb(buf, buflen, 231 "\e20\ex10NOTBOOT\ex0f" "FPP\ex0eSDVMA\ex0cVIDEO" 232 "\ex0bLORES\ex0a" "FPA\ex09" "DIAG\ex07" "CACHE" 233 "\ex06IOCACHE\ex05LOOPBACK\ex04" "DBGCACHE", 234 0xe860) 235\(rA "0xe860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>" 236.Ed 237.Pp 238An example of the new formatting style: 239.Bd -literal -offset indent 240snprintb(buf, buflen, 241 "\e177\e020b\e0LSB\e0b\e1_BITONE\e0f\e4\e4NIBBLE2\e0" 242 "f\ex10\e4BURST\e0=\e4FOUR\e0=\exfSIXTEEN\e0" 243 "b\ex1fMSB\e0\e0", 244 0x800f0701) 245\(rA "0x800f0701<LSB,NIBBLE2=0x0,BURST=0xf=SIXTEEN,MSB>" 246.Ed 247.Pp 248An example using snprintb_m: 249.Bd -literal -offset indent 250snprintb_m(buf, buflen, 251 "\e177\e020b\e0LSB\e0b\e1_BITONE\e0f\e4\e4NIBBLE2\e0" 252 "f\ex10\e4BURST\e0=\e4FOUR\e0=\exfSIXTEEN\e0" 253 "b\ex1fMSB\e0\e0", 254 0x800f0701, 34) 255\(rA "0x800f0701<LSB,NIBBLE2=0x0>\e00x800f0701<BURST=0xf=SIXTEEN,MSB>\e0" 256.Ed 257.Sh ERRORS 258.Fn snprintb 259will fail if: 260.Bl -tag -width Er 261.It Bq Er EINVAL 262The leading character does not describe a supported format, 263or 264.Fn snprintf 265failed. 266.El 267.Sh SEE ALSO 268.Xr printf 3 , 269.Xr snprintf 3 270.Sh HISTORY 271The 272.Fn snprintb 273function was originally implemented as a non-standard 274.Li %b 275format string for the kernel 276.Fn printf 277function in 278.Nx 1.5 279and earlier releases. 280It was called 281.Fn bitmask_snprintf 282in 283.Nx 5.0 284and earlier releases. 285.Sh AUTHORS 286The 287.Dq new 288format was the invention of 289.An Chris Torek . 290