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 .\" $DragonFly: src/share/man/man9/kprintf.9,v 1.5 2008/07/18 00:28:04 swildner Exp $
  29 .\"
  30 .Dd July 17, 2008
  31 .Dt KPRINTF 9
  32 .Os
  33 .Sh NAME
  34 .Nm kprintf ,
  35 .Nm ksprintf ,
  36 .Nm ksnprintf ,
  37 .Nm kvprintf ,
  38 .Nm kvsprintf ,
  39 .Nm kvsnprintf ,
  40 .Nm krateprintf ,
  41 .Nm tprintf ,
  42 .Nm uprintf ,
  43 .Nm log
  44 .Nd formatted output conversion
  45 .Sh SYNOPSIS
  46 .In sys/types.h
  47 .In sys/systm.h
  48 .Ft int
  49 .Fn kprintf "const char *format" ...
  50 .Ft int
  51 .Fn ksprintf "char *str" "const char *format" ...
  52 .Ft int
  53 .Fn ksnprintf "char *str" "size_t size" "const char *format" ...
  54 .Ft int
  55 .Fn kvprintf "const char *format" "__va_list ap"
  56 .Ft int
  57 .Fn kvsprintf "char *str" "const char *format" "__va_list ap"
  58 .Ft int
  59 .Fn kvsnprintf "char *str" "size_t size" "const char *format" "__va_list ap"
  60 .Ft void
  61 .Fn krateprintf "struct krate *rate" "const char *format" ...
  62 .Ft int
  63 .Fn tprintf "struct proc *p" "int pri" "const char *format" ...
  64 .Ft int
  65 .Fn uprintf "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 two other conversion specifiers to
 111 .Fa format :
 112 .Pp
 113 The
 114 .Cm \&%b
 115 identifier expects two arguments: an
 116 .Vt int
 117 and a
 118 .Vt "char *" .
 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 .Cm \&%D
 136 identifier is meant to assist in hexdumps.
 137 It requires two arguments: a
 138 .Vt "u_char *"
 139 pointer and a
 140 .Vt "char *"
 141 string.
 142 The memory pointed to be the pointer is output in hexadecimal one byte at
 143 a time.
 144 The string is used as a delimiter between individual bytes.
 145 If present, a width directive will specify the number of bytes to display.
 146 By default, 16 bytes of data are output.
 147 .Pp
 148 The
 149 .Fn log
 150 function uses
 151 .Xr syslog 3
 152 level values
 153 .Dv LOG_DEBUG
 154 through
 155 .Dv LOG_EMERG
 156 for its
 157 .Fa pri
 158 parameter (mistakenly called
 159 .Sq priority
 160 here).
 161 Alternatively, if a
 162 .Fa pri
 163 of \-1 is given, the message will be appended to the last log message
 164 started by a previous call to
 165 .Fn log .
 166 As these messages are generated by the kernel itself, the facility will
 167 always be
 168 .Dv LOG_KERN .
 169 .Pp
 170 The
 171 .Fn krateprintf
 172 function is a rate controlled version of
 173 .Fn kprintf .
 174 The
 175 .Fa freq
 176 member of the
 177 .Vt struct krate
 178 pointed to by
 179 .Fa rate
 180 must be initialized with the desired reporting frequency.
 181 A
 182 .Fa freq
 183 of 0 will result in no output.
 184 Initializing
 185 .Fa count
 186 to a negative value allows an initial burst.
 187 .Sh RETURN VALUES
 188 The
 189 .Fn kprintf ,
 190 .Fn ksprintf ,
 191 .Fn ksnprintf ,
 192 .Fn kvprintf ,
 193 .Fn kvsprintf ,
 194 .Fn kvsnprintf ,
 195 .Fn tprintf ,
 196 .Fn uprintf ,
 197 and
 198 .Fn log
 199 functions return the number of characters displayed.
 200 .Sh EXAMPLES
 201 This example demonstrates the use of the
 202 .Cm \&%b
 203 and
 204 .Cm \&%D
 205 conversion specifiers.
 206 The function
 207 .Bd -literal -offset indent
 208 void
 209 kprintf_test(void)
 210 {
 211
 212         kprintf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE\en");
 213         kprintf("out: %4D\en", "AAAA", ":");
 214 }
 215 .Ed
 216 .Pp
 217 will produce the following output:
 218 .Bd -literal -offset indent
 219 reg=3<BITTWO,BITONE>
 220 out: 41:41:41:41
 221 .Ed
 222 .Pp
 223 The call
 224 .Bd -literal -offset indent
 225 log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit);
 226 .Ed
 227 .Pp
 228 will add the appropriate debug message at priority
 229 .Dq Li kern.debug
 230 to the system log.
 231 .Sh SEE ALSO
 232 .Xr printf 3 ,
 233 .Xr syslog 3