1.\" $NetBSD: snprintb.3,v 1.5 2004/12/01 00:06:46 peter 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 SNPRINTB 3 39.Os 40.Sh NAME 41.Nm snprintb 42.Nd bitmask output conversion 43.Sh LIBRARY 44.Lb libutil 45.Sh SYNOPSIS 46.In util.h 47.Ft int 48.Fn "snprintb" "char *buf" "size_t buflen" "const char *fmt" "uint64_t val" 49.Sh DESCRIPTION 50The 51.Fn snprintb 52function formats a bitmask into a mnemonic form suitable for printing. 53.Pp 54This conversion is useful for decoding bit fields in device registers. 55It formats the integer 56.Fa val 57into the buffer 58.Fa buf , 59of size 60.Fa buflen , 61using a specified radix and an interpretation of 62the bits within that integer as though they were flags. 63.Pp 64The decoding directive string 65.Fa fmt 66describes how the bitfield is to be interpreted and displayed. 67The first character of 68.Fa fmt 69is a binary character representation of the 70output numeral base in which the bitfield will be printed before it is decoded. 71Recognized radix values 72.Pq "in C escape-character format" 73are 74.Li \e10 75.Pq octal , 76.Li \e12 77.Pq decimal , 78and 79.Li \e20 80.Pq hexadecimal . 81.Pp 82The remaining characters in 83.Fa fmt 84are interpreted as a list of bit-position\(endescription pairs. 85A bit-position\(endescription pair begins with a binary character value 86that represents the position of the bit being described. 87A bit position value of one describes the least significant bit. 88Whereas a position value of 32 89.Pq "octal 40, hexadecimal 20, the ASCII space character" 90describes the most significant bit. 91.Pp 92The remaining characters in a bit-position\(endescription pair are the 93characters to print should the bit being described be set. 94Description strings are delimited by the next bit position value character 95encountered 96.Pq "distinguishable by its value being \*[Le] 32" , 97or the end of the decoding directive string itself. 98.Sh RETURN VALUES 99The 100.Fn snprintb 101function returns the number of characters that are required to format the 102value 103.Fa val 104given the format string 105.Fa fmt 106excluding the terminating NUL. 107The returned string in 108.Fa buf 109is always NUL-terminated. 110.Sh EXAMPLES 111Two examples of the old formatting style: 112.Bd -literal -offset indent 113snprintb(buf, buflen, "\e10\e2BITTWO\e1BITONE", 3) 114\(rA "3\*[Lt]BITTWO,BITONE\*[Gt]" 115 116snprintb(buf, buflen 117 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 118 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 119 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE", 120 0xe860) 121\(rA "0xe860\*[Lt]NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE\*[Gt]" 122.Ed 123.Sh ERRORS 124If the buffer 125.Fa buf 126is too small to hold the formatted output, 127.Fn snprintb 128will still return the buffer, containing a truncated string. 129.Sh SEE ALSO 130.Xr snprintf 3 131.Sh HISTORY 132The 133.Fn snprintb 134function was originally implemented as a non-standard 135.Li %b 136format string for the kernel 137.Fn printf 138function in 139.Nx 1.5 140and earlier releases. 141It got implemented as 142.Fn bitmap_snprintf 143for 144.Nx 1.6 145and this version was used to implement 146.Fn snprintb . 147.Sh BUGS 148.Fn snprintb 149supports a new extended form of formatting string, which is not yet 150described here. 151