1.\" $NetBSD: snprintb.3,v 1.3 2003/04/16 13:35:15 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd July 28, 2000 38.Dt BITMASK_SNPRINTF 9 39.Os 40.Sh NAME 41.Nm snprintb 42.Nd bitmask output conversion 43.Sh SYNOPSIS 44.In util.h 45.Ft int 46.Fn "snprintb" "char *buf" "size_t buflen" "const char *fmt" "uint64_t val" 47.Sh DESCRIPTION 48The 49.Fn snprintb 50function formats a bitmask into a mnemonic form suitable for printing. 51.Pp 52This conversion is useful for decoding bit fields in device registers. 53It formats the integer 54.Fa val 55into the buffer 56.Fa buf , 57of size 58.Fa buflen , 59using a specified radix and an interpretation of 60the bits within that integer as though they were flags. 61.Pp 62The decoding directive string 63.Fa fmt 64describes how the bitfield is to be interpreted and displayed. 65The first character of 66.Fa fmt 67is a binary character representation of the 68output numeral base in which the bitfield will be printed before it is decoded. 69Recognized radix values 70.Pq "in C escape-character format" 71are 72.Li \e10 73.Pq octal , 74.Li \e12 75.Pq decimal , 76and 77.Li \e20 78.Pq hexadecimal . 79.Pp 80The remaining characters in 81.Fa fmt 82are interpreted as a list of bit-position\(endescription pairs. 83A bit-position\(endescription pair begins with a binary character value 84that represents the position of the bit being described. 85A bit position value of one describes the least significant bit. 86Whereas a position value of 32 87.Pq "octal 40, hexadecimal 20, the ASCII space character" 88describes the most significant bit. 89.Pp 90The remaining characters in a bit-position\(endescription pair are the 91characters to print should the bit being described be set. 92Description strings are delimited by the next bit position value character 93encountered 94.Pq "distinguishable by its value being \*[Le] 32" , 95or the end of the decoding directive string itself. 96.Sh RETURN VALUES 97The 98.Fn snprintb 99function returns the number of characters that are required to format the 100value 101.Fa val 102given the format string 103.Fa fmt 104excluding the terminating NUL. 105The returned string in 106.Fa buf 107is always NUL-terminated. 108.Sh EXAMPLES 109Two examples of the old formatting style: 110.Bd -literal -offset indent 111snprintb(buf, buflen, "\e10\e2BITTWO\e1BITONE", 3) 112\(rA "3\*[Lt]BITTWO,BITONE\*[Gt]" 113 114snprintb(buf, buflen 115 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 116 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 117 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE", 118 0xe860) 119\(rA "0xe860\*[Lt]NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE\*[Gt]" 120.Ed 121.Sh ERRORS 122If the buffer 123.Fa buf 124is too small to hold the formatted output, 125.Fn snprintb 126will still return the buffer, containing a truncated string. 127.Sh SEE ALSO 128.Xr snprintf 3 129.Sh HISTORY 130The 131.Fn snprintb 132function was originally implemented as a non-standard 133.Li %b 134format string for the kernel 135.Fn printf 136function in 137.Nx 1.5 138and earlier releases. 139It got implemented as 140.Fn bitmap_snprintf 141for 142.Nx 1.6 143and this version was used to implement 144.Fn snprintb . 145.Sh BUGS 146.Fn snprintb 147supports a new extended form of formatting string, which is not yet 148described here. 149