lib/libutil/snprintb.3

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