man2/syslog.2

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