1.\" $NetBSD: snprintb.3,v 1.6 2008/04/30 13:10:52 martin 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 July 28, 2000 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.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. 56.Pp 57The decoding directive string 58.Fa fmt 59describes how the bitfield is to be interpreted and displayed. 60The first character of 61.Fa fmt 62is a binary character representation of the 63output numeral base in which the bitfield will be printed before it is decoded. 64Recognized radix values 65.Pq "in C escape-character format" 66are 67.Li \e10 68.Pq octal , 69.Li \e12 70.Pq decimal , 71and 72.Li \e20 73.Pq hexadecimal . 74.Pp 75The remaining characters in 76.Fa fmt 77are interpreted as a list of bit-position\(endescription pairs. 78A bit-position\(endescription pair begins with a binary character value 79that represents the position of the bit being described. 80A bit position value of one describes the least significant bit. 81Whereas a position value of 32 82.Pq "octal 40, hexadecimal 20, the ASCII space character" 83describes the most significant bit. 84.Pp 85The remaining characters in a bit-position\(endescription pair are the 86characters to print should the bit being described be set. 87Description strings are delimited by the next bit position value character 88encountered 89.Pq "distinguishable by its value being \*[Le] 32" , 90or the end of the decoding directive string itself. 91.Sh RETURN VALUES 92The 93.Fn snprintb 94function returns the number of characters that are required to format the 95value 96.Fa val 97given the format string 98.Fa fmt 99excluding the terminating NUL. 100The returned string in 101.Fa buf 102is always NUL-terminated. 103.Sh EXAMPLES 104Two examples of the old formatting style: 105.Bd -literal -offset indent 106snprintb(buf, buflen, "\e10\e2BITTWO\e1BITONE", 3) 107\(rA "3\*[Lt]BITTWO,BITONE\*[Gt]" 108 109snprintb(buf, buflen 110 "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" 111 "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" 112 "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE", 113 0xe860) 114\(rA "0xe860\*[Lt]NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE\*[Gt]" 115.Ed 116.Sh ERRORS 117If the buffer 118.Fa buf 119is too small to hold the formatted output, 120.Fn snprintb 121will still return the buffer, containing a truncated string. 122.Sh SEE ALSO 123.Xr snprintf 3 124.Sh HISTORY 125The 126.Fn snprintb 127function was originally implemented as a non-standard 128.Li %b 129format string for the kernel 130.Fn printf 131function in 132.Nx 1.5 133and earlier releases. 134It got implemented as 135.Fn bitmap_snprintf 136for 137.Nx 1.6 138and this version was used to implement 139.Fn snprintb . 140.Sh BUGS 141.Fn snprintb 142supports a new extended form of formatting string, which is not yet 143described here. 144