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 December 21, 2012
  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 void
  60 .Fn krateprintf "struct krate *rate" "const char *format" ...
  61 .Ft int
  62 .Fn tprintf "struct proc *p" "int pri" "const char *format" ...
  63 .Ft int
  64 .Fn uprintf "const char *format" ...
  65 .In sys/syslog.h
  66 .Ft int
  67 .Fn log "int pri" "const char *format" ...
  68 .Sh DESCRIPTION
  69 The
  70 .Nm
  71 family of functions are similar to the
  72 .Xr printf 3
  73 family of functions.
  74 The different functions each use a different output stream.
  75 The
  76 .Fn uprintf
  77 function outputs to the current process' controlling tty, while
  78 .Fn kprintf ,
  79 .Fn ksprintf ,
  80 .Fn ksnprintf ,
  81 .Fn kvprintf ,
  82 .Fn kvsprintf
  83 and
  84 .Fn kvsnprintf
  85 write to the console as well as to the logging facility.
  86 The
  87 .Fn tprintf
  88 function outputs to the tty associated with the process
  89 .Fa p
  90 and the logging facility if
  91 .Fa pri
  92 is not \-1.
  93 The
  94 .Fn log
  95 function sends the message to the kernel logging facility, using
  96 the log level as indicated by
  97 .Fa pri .
  98 .Pp
  99 Each of these related functions use the
 100 .Fa format ,
 101 .Fa str ,
 102 .Fa size
 103 and
 104 .Fa va
 105 parameters in the same manner as
 106 .Xr printf 3 .
 107 However, the
 108 .Nm
 109 functions add another conversion specifier to
 110 .Fa format :
 111 .Pp
 112 The
 113 .Cm \&%b
 114 identifier expects two arguments: an
 115 .Vt int
 116 and a
 117 .Vt "char *" .
 118 These are used as a register value and a print mask for decoding bitmasks.
 119 The print mask is made up of two parts: the base and the
 120 arguments.
 121 The base value is the output base expressed as an integer value;
 122 for example, \e10 gives octal and \e20 gives hexadecimal.
 123 The arguments are made up of a sequence of bit identifiers.
 124 Each bit identifier begins with an integer value which is the number of the
 125 bit (starting from 1) this identifier describes.
 126 The rest of the identifier is a string of characters containing the name of
 127 the bit.
 128 The string is terminated by either the bit number at the start of the next
 129 bit identifier or
 130 .Dv NUL
 131 for the last bit identifier.
 132 .Pp
 133 The
 134 .Fn log
 135 function uses
 136 .Xr syslog 3
 137 level values
 138 .Dv LOG_DEBUG
 139 through
 140 .Dv LOG_EMERG
 141 for its
 142 .Fa pri
 143 parameter (mistakenly called
 144 .Sq priority
 145 here).
 146 Alternatively, if a
 147 .Fa pri
 148 of \-1 is given, the message will be appended to the last log message
 149 started by a previous call to
 150 .Fn log .
 151 As these messages are generated by the kernel itself, the facility will
 152 always be
 153 .Dv LOG_KERN .
 154 .Pp
 155 The
 156 .Fn krateprintf
 157 function is a rate controlled version of
 158 .Fn kprintf .
 159 The
 160 .Fa freq
 161 member of the
 162 .Vt struct krate
 163 pointed to by
 164 .Fa rate
 165 must be initialized with the desired reporting frequency.
 166 A
 167 .Fa freq
 168 of 0 will result in no output.
 169 Initializing
 170 .Fa count
 171 to a negative value allows an initial burst.
 172 .Sh RETURN VALUES
 173 The
 174 .Fn kprintf ,
 175 .Fn ksprintf ,
 176 .Fn ksnprintf ,
 177 .Fn kvprintf ,
 178 .Fn kvsprintf ,
 179 .Fn kvsnprintf ,
 180 .Fn tprintf ,
 181 .Fn uprintf ,
 182 and
 183 .Fn log
 184 functions return the number of characters displayed.
 185 .Sh EXAMPLES
 186 This example demonstrates the use of the
 187 .Cm \&%b
 188 conversion specifier.
 189 The function
 190 .Bd -literal -offset indent
 191 void
 192 kprintf_test(void)
 193 {
 194
 195         kprintf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE\en");
 196 }
 197 .Ed
 198 .Pp
 199 will produce the following output:
 200 .Bd -literal -offset indent
 201 reg=3<BITTWO,BITONE>
 202 .Ed
 203 .Pp
 204 The call
 205 .Bd -literal -offset indent
 206 log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit);
 207 .Ed
 208 .Pp
 209 will add the appropriate debug message at priority
 210 .Dq Li kern.debug
 211 to the system log.
 212 .Sh SEE ALSO
 213 .Xr printf 3 ,
 214 .Xr syslog 3