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