share/man/man9/kprintf.9

   1 .\"
   2 .\" Copyright (c) 2001 Andrew R. Reiter
   3 .\" Copyright (c) 2004 Joerg Wunsch
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  20 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  21 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  22 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  23 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD: src/share/man/man9/printf.9,v 1.8 2006/09/08 14:05:03 ru Exp $
  28 .\"
  29 .Dd September 29, 2019
  30 .Dt KPRINTF 9
  31 .Os
  32 .Sh NAME
  33 .Nm kprintf ,
  34 .Nm ksprintf ,
  35 .Nm ksnprintf ,
  36 .Nm kvprintf ,
  37 .Nm kvsprintf ,
  38 .Nm kvsnprintf ,
  39 .Nm krateprintf ,
  40 .Nm tprintf ,
  41 .Nm uprintf ,
  42 .Nm log
  43 .Nd formatted output conversion
  44 .Sh SYNOPSIS
  45 .In sys/types.h
  46 .In sys/systm.h
  47 .Ft int
  48 .Fn kprintf "const char *format" ...
  49 .Ft int
  50 .Fn ksprintf "char *str" "const char *format" ...
  51 .Ft int
  52 .Fn ksnprintf "char *str" "size_t size" "const char *format" ...
  53 .Ft int
  54 .Fn kvprintf "const char *format" "__va_list ap"
  55 .Ft int
  56 .Fn kvsprintf "char *str" "const char *format" "__va_list ap"
  57 .Ft int
  58 .Fn kvsnprintf "char *str" "size_t size" "const char *format" "__va_list ap"
  59 .Ft int
  60 .Fn krateprintf "struct krate *rate" "const char *format" ...
  61 .Ft int
  62 .Fn uprintf "const char *format" ...
  63 .In sys/tprintf.h
  64 .Ft int
  65 .Fn tprintf "struct proc *p" "int pri" "const char *format" ...
  66 .In sys/syslog.h
  67 .Ft int
  68 .Fn log "int pri" "const char *format" ...
  69 .Sh DESCRIPTION
  70 The
  71 .Nm
  72 family of functions are similar to the
  73 .Xr printf 3
  74 family of functions.
  75 The different functions each use a different output stream.
  76 The
  77 .Fn uprintf
  78 function outputs to the current process' controlling tty, while
  79 .Fn kprintf ,
  80 .Fn ksprintf ,
  81 .Fn ksnprintf ,
  82 .Fn kvprintf ,
  83 .Fn kvsprintf
  84 and
  85 .Fn kvsnprintf
  86 write to the console as well as to the logging facility.
  87 The
  88 .Fn tprintf
  89 function outputs to the tty associated with the process
  90 .Fa p
  91 and the logging facility if
  92 .Fa pri
  93 is not \-1.
  94 The
  95 .Fn log
  96 function sends the message to the kernel logging facility, using
  97 the log level as indicated by
  98 .Fa pri .
  99 .Pp
 100 Each of these related functions use the
 101 .Fa format ,
 102 .Fa str ,
 103 .Fa size
 104 and
 105 .Fa va
 106 parameters in the same manner as
 107 .Xr printf 3 .
 108 However, the
 109 .Nm
 110 functions add another conversion specifier to
 111 .Fa format :
 112 .Pp
 113 The
 114 .Cm \&%pb%i
 115 identifier expects two arguments: an
 116 .Vt "char *"
 117 and a
 118 .Vt int .
 119 These are used as a register value and a print mask for decoding bitmasks.
 120 The print mask is made up of two parts: the base and the
 121 arguments.
 122 The base value is the output base expressed as an integer value;
 123 for example, \e10 gives octal and \e20 gives hexadecimal.
 124 The arguments are made up of a sequence of bit identifiers.
 125 Each bit identifier begins with an integer value which is the number of the
 126 bit (starting from 1) this identifier describes.
 127 The rest of the identifier is a string of characters containing the name of
 128 the bit.
 129 The string is terminated by either the bit number at the start of the next
 130 bit identifier or
 131 .Dv NUL
 132 for the last bit identifier.
 133 .Pp
 134 The
 135 .Fn log
 136 function uses
 137 .Xr syslog 3
 138 level values
 139 .Dv LOG_DEBUG
 140 through
 141 .Dv LOG_EMERG
 142 for its
 143 .Fa pri
 144 parameter (mistakenly called
 145 .Sq priority
 146 here).
 147 Alternatively, if a
 148 .Fa pri
 149 of \-1 is given, the message will be appended to the last log message
 150 started by a previous call to
 151 .Fn log .
 152 As these messages are generated by the kernel itself, the facility will
 153 always be
 154 .Dv LOG_KERN .
 155 .Pp
 156 The
 157 .Fn krateprintf
 158 function is a rate controlled version of
 159 .Fn kprintf .
 160 The
 161 .Fa freq
 162 member of the
 163 .Vt struct krate
 164 pointed to by
 165 .Fa rate
 166 must be initialized with the desired reporting frequency.
 167 A
 168 .Fa freq
 169 of 0 will result in no output.
 170 Initializing
 171 .Fa count
 172 to a negative value allows an initial burst.
 173 .Sh RETURN VALUES
 174 The
 175 .Fn kprintf ,
 176 .Fn ksprintf ,
 177 .Fn ksnprintf ,
 178 .Fn kvprintf ,
 179 .Fn kvsprintf ,
 180 .Fn kvsnprintf ,
 181 .Fn tprintf ,
 182 .Fn uprintf ,
 183 and
 184 .Fn log
 185 functions return the number of characters displayed.
 186 .Pp
 187 The
 188 .Fn krateprintf
 189 function returns 1 or 0, depending on whether anything was printed or not,
 190 allowing code to issue additional
 191 .Fn kprintf Ns s
 192 if desired.
 193 .Sh EXAMPLES
 194 This example demonstrates the use of the
 195 .Cm \&%pb%i
 196 conversion specifier.
 197 The function
 198 .Bd -literal -offset indent
 199 void
 200 kprintf_test(void)
 201 {
 202
 203         kprintf("reg=%pb%i\en", "\e10\e2BITTWO\e1BITONE\en", 3);
 204 }
 205 .Ed
 206 .Pp
 207 will produce the following output:
 208 .Bd -literal -offset indent
 209 reg=3<BITTWO,BITONE>
 210 .Ed
 211 .Pp
 212 The call
 213 .Bd -literal -offset indent
 214 log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit);
 215 .Ed
 216 .Pp
 217 will add the appropriate debug message at priority
 218 .Dq Li kern.debug
 219 to the system log.
 220 .Sh SEE ALSO
 221 .Xr printf 3 ,
 222 .Xr syslog 3