man2/syslog.2

   1 '\" t
   2 .\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl)
   3 .\" and Copyright (C) 2012, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" Written 11 June 1995 by Andries Brouwer <aeb@cwi.nl>
  28 .\" 2008-02-15, Jeremy Kerr <jk@ozlabs.org>
  29 .\"     Add info on command type 10; add details on types 6, 7, 8, & 9.
  30 .\" 2008-02-15, Michael Kerrisk <mtk.manpages@gmail.com>
  31 .\"     Update LOG_BUF_LEN details; update RETURN VALUE section.
  32 .\"
  33 .TH SYSLOG 2  2015-05-07 "Linux" "Linux Programmer's Manual"
  34 .SH NAME
  35 syslog, klogctl \- read and/or clear kernel message ring buffer;
  36 set console_loglevel
  37 .SH SYNOPSIS
  38 .nf
  39 .BI "int syslog(int " type ", char *" bufp ", int " len );
  40 .B  "                /* No wrapper provided in glibc */"
  41 .PP
  42 /* The glibc interface */
  43 .br
  44 .B "#include <sys/klog.h>"
  45 .PP
  46 .BI "int klogctl(int " type ", char *" bufp ", int " len );
  47 .fi
  48 .SH DESCRIPTION
  49 .IR Note :
  50 Probably, you are looking for the C library function
  51 .BR syslog (),
  52 which talks to
  53 .BR syslogd (8);
  54 see
  55 .BR syslog (3)
  56 for details.
  57 .PP
  58 This page describes the kernel
  59 .BR syslog ()
  60 system call, which is used to control the kernel
  61 .IR printk ()
  62 buffer; the glibc wrapper function for the system call is called
  63 .BR klogctl ().
  64 .SS The kernel log buffer
  65 The kernel has a cyclic buffer of length
  66 .B LOG_BUF_LEN
  67 in which messages given as arguments to the kernel function
  68 .BR printk ()
  69 are stored (regardless of their log level).
  70 In early kernels,
  71 .B LOG_BUF_LEN
  72 had the value 4096;
  73 from kernel 1.3.54, it was 8192;
  74 from kernel 2.1.113, it was 16384;
  75 since kernel 2.4.23/2.6, the value is a kernel configuration option
  76 .RB ( CONFIG_LOG_BUF_SHIFT ,
  77 default value dependent on the architecture).
  78 .\" Under "General setup" ==> "Kernel log buffer size"
  79 .\" For 2.6, precisely the option seems to have appeared in 2.5.55.
  80 Since Linux 2.6.6, the size can be queried with command type 10 (see below).
  81 .SS Commands
  82 The \fItype\fP argument determines the action taken by this function.
  83 The list below specifies the values for
  84 .IR type .
  85 The symbolic names are defined in the kernel source,
  86 but are not exported to user space;
  87 you will either need to use the numbers, or define the names yourself.
  88 .TP
  89 .BR SYSLOG_ACTION_CLOSE " (0)"
  90 Close the log.
  91 Currently a NOP.
  92 .TP
  93 .BR SYSLOG_ACTION_OPEN " (1)"
  94 Open the log.
  95 Currently a NOP.
  96 .TP
  97 .BR SYSLOG_ACTION_READ " (2)"
  98 Read from the log.
  99 The call
 100 waits until the kernel log buffer is nonempty, and then reads
 101 at most \fIlen\fP bytes into the buffer pointed to by
 102 .IR bufp .
 103 The call returns the number of bytes read.
 104 Bytes read from the log disappear from the log buffer:
 105 the information can be read only once.
 106 This is the function executed by the kernel when a user program reads
 107 .IR /proc/kmsg .
 108 .TP
 109 .BR SYSLOG_ACTION_READ_ALL " (3)"
 110 Read all messages remaining in the ring buffer,
 111 placing them in the buffer pointed to by
 112 .IR bufp .
 113 The call reads the last \fIlen\fP
 114 bytes from the log buffer (nondestructively),
 115 but will not read more than was written into the buffer since the
 116 last "clear ring buffer" command (see command 5 below)).
 117 The call returns the number of bytes read.
 118 .TP
 119 .BR SYSLOG_ACTION_READ_CLEAR " (4)"
 120 Read and clear all messages remaining in the ring buffer.
 121 The call does precisely the same as for a
 122 .I type
 123 of 3, but also executes the "clear ring buffer" command.
 124 .TP
 125 .BR SYSLOG_ACTION_CLEAR " (5)"
 126 The call executes just the "clear ring buffer" command.
 127 The
 128 .I bufp
 129 and
 130 .I len
 131 arguments are ignored.
 132 .IP
 133 This command does not really clear the ring buffer.
 134 Rather, it sets a kernel bookkeeping variable that
 135 determines the results returned by commands 3
 136 .RB ( SYSLOG_ACTION_READ_ALL )
 137 and 4
 138 .RB ( SYSLOG_ACTION_READ_CLEAR ).
 139 This command has no effect on commands 2
 140 .RB ( SYSLOG_ACTION_READ )
 141 and 9
 142 .RB ( SYSLOG_ACTION_SIZE_UNREAD ).
 143 .TP
 144 .BR SYSLOG_ACTION_CONSOLE_OFF " (6)"
 145 The command saves the current value of
 146 .I console_loglevel
 147 and then sets
 148 .I console_loglevel
 149 to
 150 .IR minimum_console_loglevel ,
 151 so that no messages are printed to the console.
 152 Before Linux 2.6.32,
 153 .\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245
 154 the command simply sets
 155 .I console_loglevel
 156 to
 157 .IR minimum_console_loglevel .
 158 See the discussion of
 159 .IR /proc/sys/kernel/printk ,
 160 below.
 161 .IP
 162 The
 163 .I bufp
 164 and
 165 .I len
 166 arguments are ignored.
 167 .TP
 168 .BR SYSLOG_ACTION_CONSOLE_ON " (7)"
 169 If a previous
 170 .B SYSLOG_ACTION_CONSOLE_OFF
 171 command has been performed,
 172 this command restores
 173 .I console_loglevel
 174 to the value that was saved by that command.
 175 Before Linux 2.6.32,
 176 .\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245
 177 this command simply sets
 178 .I console_loglevel
 179 to
 180 .IR default_console_loglevel .
 181 See the discussion of
 182 .IR /proc/sys/kernel/printk ,
 183 below.
 184 .IP
 185 The
 186 .I bufp
 187 and
 188 .I len
 189 arguments are ignored.
 190 .TP
 191 .BR SYSLOG_ACTION_CONSOLE_LEVEL " (8)"
 192 The call sets
 193 .I console_loglevel
 194 to the value given in
 195 .IR len ,
 196 which must be an integer between 1 and 8 (inclusive).
 197 The kernel silently enforces a minimum value of
 198 .IR minimum_console_loglevel
 199 for
 200 .IR len .
 201 See the
 202 .IR "log level"
 203 section for details.
 204 The
 205 .I bufp
 206 argument is ignored.
 207 .TP
 208 .BR SYSLOG_ACTION_SIZE_UNREAD " (9) (since Linux 2.4.10)"
 209 The call
 210 returns the number of bytes currently available to be read
 211 from the kernel log buffer via command 2
 212 .RB ( SYSLOG_ACTION_READ ).
 213 The
 214 .I bufp
 215 and
 216 .I len
 217 arguments are ignored.
 218 .TP
 219 .BR SYSLOG_ACTION_SIZE_BUFFER " (10) (since Linux 2.6.6)"
 220 This command returns the total size of the kernel log buffer.
 221 The
 222 .I bufp
 223 and
 224 .I len
 225 arguments are ignored.
 226 .PP
 227 All commands except 3 and 10 require privilege.
 228 In Linux kernels before 2.6.37,
 229 command types 3 and 10 are allowed to unprivileged processes;
 230 since Linux 2.6.37,
 231 these commands are allowed to unprivileged processes only if
 232 .IR /proc/sys/kernel/dmesg_restrict
 233 has the value 0.
 234 Before Linux 2.6.37, "privileged" means that the caller has the
 235 .BR CAP_SYS_ADMIN
 236 capability.
 237 Since Linux 2.6.37,
 238 "privileged" means that the caller has either the
 239 .BR CAP_SYS_ADMIN
 240 capability (now deprecated for this purpose) or the (new)
 241 .BR CAP_SYSLOG
 242 capability.
 243 .\"
 244 .\"
 245 .SS /proc/sys/kernel/printk
 246 .I /proc/sys/kernel/printk
 247 is a writable file containing four integer values that influence kernel
 248 .I printk()
 249 behavior when printing or logging error messages.
 250 The four values are:
 251 .TP
 252 .I console_loglevel
 253 Only messages with a log level lower than this value will
 254 be printed to the console.
 255 The default value for this field is
 256 .B DEFAULT_CONSOLE_LOGLEVEL
 257 (7), but it is set to
 258 4 if the kernel command line contains the word "quiet", \" since Linux 2.4
 259 10 if the kernel command line contains the word "debug",
 260 and to 15 in case
 261 of a kernel fault (the 10 and 15 are just silly, and equivalent to 8).
 262 The value of
 263 .IR console_loglevel
 264 can be set (to a value in the range 1\(en8) by a
 265 .BR syslog ()
 266 call with a
 267 .I type
 268 of 8.
 269 .TP
 270 .I default_message_loglevel
 271 This value will be used as the log level for
 272 .IR printk()
 273 messages that do not have an explicit level.
 274 Up to and including Linux 2.6.38,
 275 the hard-coded default value for this field was 4
 276 .RB ( KERN_WARNING );
 277 since Linux 2.6.39,
 278 .\" commit 5af5bcb8d37f99ba415a1adc6da71051b84f93a5
 279 the default value is a defined by the kernel configuration option
 280 .BR CONFIG_DEFAULT_MESSAGE_LOGLEVEL ,
 281 which defaults to 4.
 282 .TP
 283 .I minimum_console_loglevel
 284 The value in this field is the minimum value to which
 285 .I console_loglevel
 286 can be set.
 287 .TP
 288 .I default_console_loglevel
 289 This is the default value for
 290 .IR console_loglevel .
 291 .\"
 292 .\"
 293 .SS The log level
 294 Every
 295 .IR printk ()
 296 message has its own log level.
 297 If the log level is not explicitly specified as part of the message,
 298 it defaults to
 299 .IR default_message_loglevel .
 300 The conventional meaning of the log level is as follows:
 301 .TS
 302 lB lB lB
 303 lB c l.
 304 Kernel constant Level value     Meaning
 305 KERN_EMERG      0       System is unusable
 306 KERN_ALERT      1       Action must be taken immediately
 307 KERN_CRIT       2       Critical conditions
 308 KERN_ERR        3       Error conditions
 309 KERN_WARNING    4       Warning conditions
 310 KERN_NOTICE     5       Normal but significant condition
 311 KERN_INFO       6       Informational
 312 KERN_DEBUG      7       Debug-level messages
 313 .TE
 314 .sp 1
 315 The kernel
 316 .IR printk()
 317 routine will print a message on the
 318 console only if it has a log level less than the value of
 319 .IR console_loglevel .
 320 .SH RETURN VALUE
 321 For \fItype\fP equal to 2, 3, or 4, a successful call to
 322 .BR syslog ()
 323 returns the number
 324 of bytes read.
 325 For \fItype\fP 9,
 326 .BR syslog ()
 327 returns the number of bytes currently
 328 available to be read on the kernel log buffer.
 329 For \fItype\fP 10,
 330 .BR syslog ()
 331 returns the total size of the kernel log buffer.
 332 For other values of \fItype\fP, 0 is returned on success.
 333 .PP
 334 In case of error, \-1 is returned,
 335 and \fIerrno\fP is set to indicate the error.
 336 .SH ERRORS
 337 .TP
 338 .B EINVAL
 339 Bad arguments (e.g.,
 340 bad
 341 .IR type ;
 342 or for
 343 .I type
 344 2, 3, or 4,
 345 .I buf
 346 is NULL,
 347 or
 348 .I len
 349 is less than zero; or for
 350 .I type
 351 8, the
 352 .I level
 353 is outside the range 1 to 8).
 354 .TP
 355 .B ENOSYS
 356 This
 357 .BR syslog ()
 358 system call is not available, because the kernel was compiled with the
 359 .BR CONFIG_PRINTK
 360 kernel-configuration option disabled.
 361 .TP
 362 .B EPERM
 363 An attempt was made to change
 364 .I console_loglevel
 365 or clear the kernel
 366 message ring buffer by a process without sufficient privilege
 367 (more precisely: without the
 368 .B CAP_SYS_ADMIN
 369 or
 370 .BR CAP_SYSLOG
 371 capability).
 372 .TP
 373 .B ERESTARTSYS
 374 System call was interrupted by a signal; nothing was read.
 375 (This can be seen only during a trace.)
 376 .SH CONFORMING TO
 377 This system call is Linux-specific and should not be used in programs
 378 intended to be portable.
 379 .SH NOTES
 380 From the very start, people noted that it is unfortunate that
 381 a system call and a library routine of the same name are entirely
 382 different animals.
 383 .\" In libc4 and libc5 the number of this call was defined by
 384 .\" .BR SYS_klog .
 385 .\" In glibc 2.0 the syscall is baptized
 386 .\" .BR klogctl ().
 387 .SH SEE ALSO
 388 .BR dmesg (1),
 389 .BR syslog (3),
 390 .BR capabilities (7)