diff options
Diffstat (limited to 'man/man2/syslog.2')
| -rw-r--r-- | man/man2/syslog.2 | 378 |
1 files changed, 378 insertions, 0 deletions
diff --git a/man/man2/syslog.2 b/man/man2/syslog.2 new file mode 100644 index 000000000..15426badf --- /dev/null +++ b/man/man2/syslog.2 @@ -0,0 +1,378 @@ +'\" t +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2012, 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Written 11 June 1995 by Andries Brouwer <aeb@cwi.nl> +.\" 2008-02-15, Jeremy Kerr <jk@ozlabs.org> +.\" Add info on command type 10; add details on types 6, 7, 8, & 9. +.\" 2008-02-15, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Update LOG_BUF_LEN details; update RETURN VALUE section. +.\" +.TH syslog 2 (date) "Linux man-pages (unreleased)" +.SH NAME +syslog, klogctl \- read and/or clear kernel message ring buffer; +set console_loglevel +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <sys/klog.h>" " /* Definition of " SYSLOG_* " constants */" +.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" +.B #include <unistd.h> +.P +.BI "int syscall(SYS_syslog, int " type ", char *" bufp ", int " len ); +.P +/* The glibc interface */ +.B #include <sys/klog.h> +.P +.BI "int klogctl(int " type ", char *" bufp ", int " len ); +.fi +.SH DESCRIPTION +.IR Note : +Probably, you are looking for the C library function +.BR syslog (), +which talks to +.BR syslogd (8); +see +.BR syslog (3) +for details. +.P +This page describes the kernel +.BR syslog () +system call, which is used to control the kernel +.IR printk () +buffer; the glibc wrapper function for the system call is called +.BR klogctl (). +.SS The kernel log buffer +The kernel has a cyclic buffer of length +.B LOG_BUF_LEN +in which messages given as arguments to the kernel function +.BR printk () +are stored (regardless of their log level). +In early kernels, +.B LOG_BUF_LEN +had the value 4096; +from Linux 1.3.54, it was 8192; +from Linux 2.1.113, it was 16384; +since Linux 2.4.23/2.6, the value is a kernel configuration option +.RB ( CONFIG_LOG_BUF_SHIFT , +default value dependent on the architecture). +.\" Under "General setup" ==> "Kernel log buffer size" +.\" For Linux 2.6, precisely the option seems to have appeared in Linux 2.5.55. +Since Linux 2.6.6, the size can be queried with command type 10 (see below). +.SS Commands +The \fItype\fP argument determines the action taken by this function. +The list below specifies the values for +.IR type . +The symbolic names are defined in the kernel source, +but are not exported to user space; +you will either need to use the numbers, or define the names yourself. +.TP +.BR SYSLOG_ACTION_CLOSE " (0)" +Close the log. +Currently a NOP. +.TP +.BR SYSLOG_ACTION_OPEN " (1)" +Open the log. +Currently a NOP. +.TP +.BR SYSLOG_ACTION_READ " (2)" +Read from the log. +The call +waits until the kernel log buffer is nonempty, and then reads +at most \fIlen\fP bytes into the buffer pointed to by +.IR bufp . +The call returns the number of bytes read. +Bytes read from the log disappear from the log buffer: +the information can be read only once. +This is the function executed by the kernel when a user program reads +.IR /proc/kmsg . +.TP +.BR SYSLOG_ACTION_READ_ALL " (3)" +Read all messages remaining in the ring buffer, +placing them in the buffer pointed to by +.IR bufp . +The call reads the last \fIlen\fP +bytes from the log buffer (nondestructively), +but will not read more than was written into the buffer since the +last "clear ring buffer" command (see command 5 below)). +The call returns the number of bytes read. +.TP +.BR SYSLOG_ACTION_READ_CLEAR " (4)" +Read and clear all messages remaining in the ring buffer. +The call does precisely the same as for a +.I type +of 3, but also executes the "clear ring buffer" command. +.TP +.BR SYSLOG_ACTION_CLEAR " (5)" +The call executes just the "clear ring buffer" command. +The +.I bufp +and +.I len +arguments are ignored. +.IP +This command does not really clear the ring buffer. +Rather, it sets a kernel bookkeeping variable that +determines the results returned by commands 3 +.RB ( SYSLOG_ACTION_READ_ALL ) +and 4 +.RB ( SYSLOG_ACTION_READ_CLEAR ). +This command has no effect on commands 2 +.RB ( SYSLOG_ACTION_READ ) +and 9 +.RB ( SYSLOG_ACTION_SIZE_UNREAD ). +.TP +.BR SYSLOG_ACTION_CONSOLE_OFF " (6)" +The command saves the current value of +.I console_loglevel +and then sets +.I console_loglevel +to +.IR minimum_console_loglevel , +so that no messages are printed to the console. +Before Linux 2.6.32, +.\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245 +the command simply sets +.I console_loglevel +to +.IR minimum_console_loglevel . +See the discussion of +.IR /proc/sys/kernel/printk , +below. +.IP +The +.I bufp +and +.I len +arguments are ignored. +.TP +.BR SYSLOG_ACTION_CONSOLE_ON " (7)" +If a previous +.B SYSLOG_ACTION_CONSOLE_OFF +command has been performed, +this command restores +.I console_loglevel +to the value that was saved by that command. +Before Linux 2.6.32, +.\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245 +this command simply sets +.I console_loglevel +to +.IR default_console_loglevel . +See the discussion of +.IR /proc/sys/kernel/printk , +below. +.IP +The +.I bufp +and +.I len +arguments are ignored. +.TP +.BR SYSLOG_ACTION_CONSOLE_LEVEL " (8)" +The call sets +.I console_loglevel +to the value given in +.IR len , +which must be an integer between 1 and 8 (inclusive). +The kernel silently enforces a minimum value of +.I minimum_console_loglevel +for +.IR len . +See the +.I log level +section for details. +The +.I bufp +argument is ignored. +.TP +.BR SYSLOG_ACTION_SIZE_UNREAD " (9) (since Linux 2.4.10)" +The call +returns the number of bytes currently available to be read +from the kernel log buffer via command 2 +.RB ( SYSLOG_ACTION_READ ). +The +.I bufp +and +.I len +arguments are ignored. +.TP +.BR SYSLOG_ACTION_SIZE_BUFFER " (10) (since Linux 2.6.6)" +This command returns the total size of the kernel log buffer. +The +.I bufp +and +.I len +arguments are ignored. +.P +All commands except 3 and 10 require privilege. +In Linux kernels before Linux 2.6.37, +command types 3 and 10 are allowed to unprivileged processes; +since Linux 2.6.37, +these commands are allowed to unprivileged processes only if +.I /proc/sys/kernel/dmesg_restrict +has the value 0. +Before Linux 2.6.37, "privileged" means that the caller has the +.B CAP_SYS_ADMIN +capability. +Since Linux 2.6.37, +"privileged" means that the caller has either the +.B CAP_SYS_ADMIN +capability (now deprecated for this purpose) or the (new) +.B CAP_SYSLOG +capability. +.\" +.\" +.SS /proc/sys/kernel/printk +.I /proc/sys/kernel/printk +is a writable file containing four integer values that influence kernel +.I printk() +behavior when printing or logging error messages. +The four values are: +.TP +.I console_loglevel +Only messages with a log level lower than this value will +be printed to the console. +The default value for this field is +.B DEFAULT_CONSOLE_LOGLEVEL +(7), but it is set to +4 if the kernel command line contains the word "quiet",\" since Linux 2.4 +10 if the kernel command line contains the word "debug", +and to 15 in case +of a kernel fault (the 10 and 15 are just silly, and equivalent to 8). +The value of +.I console_loglevel +can be set (to a value in the range 1\[en]8) by a +.BR syslog () +call with a +.I type +of 8. +.TP +.I default_message_loglevel +This value will be used as the log level for +.I printk() +messages that do not have an explicit level. +Up to and including Linux 2.6.38, +the hard-coded default value for this field was 4 +.RB ( KERN_WARNING ); +since Linux 2.6.39, +.\" commit 5af5bcb8d37f99ba415a1adc6da71051b84f93a5 +the default value is defined by the kernel configuration option +.BR CONFIG_DEFAULT_MESSAGE_LOGLEVEL , +which defaults to 4. +.TP +.I minimum_console_loglevel +The value in this field is the minimum value to which +.I console_loglevel +can be set. +.TP +.I default_console_loglevel +This is the default value for +.IR console_loglevel . +.\" +.\" +.SS The log level +Every +.IR printk () +message has its own log level. +If the log level is not explicitly specified as part of the message, +it defaults to +.IR default_message_loglevel . +The conventional meaning of the log level is as follows: +.TS +lB lB lB +lB c l. +Kernel constant Level value Meaning +KERN_EMERG 0 System is unusable +KERN_ALERT 1 T{ +Action must be taken immediately +T} +KERN_CRIT 2 Critical conditions +KERN_ERR 3 Error conditions +KERN_WARNING 4 Warning conditions +KERN_NOTICE 5 T{ +Normal but significant condition +T} +KERN_INFO 6 Informational +KERN_DEBUG 7 Debug-level messages +.TE +.P +The kernel +.I printk() +routine will print a message on the +console only if it has a log level less than the value of +.IR console_loglevel . +.SH RETURN VALUE +For \fItype\fP equal to 2, 3, or 4, a successful call to +.BR syslog () +returns the number +of bytes read. +For \fItype\fP 9, +.BR syslog () +returns the number of bytes currently +available to be read on the kernel log buffer. +For \fItype\fP 10, +.BR syslog () +returns the total size of the kernel log buffer. +For other values of \fItype\fP, 0 is returned on success. +.P +In case of error, \-1 is returned, +and \fIerrno\fP is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Bad arguments (e.g., +bad +.IR type ; +or for +.I type +2, 3, or 4, +.I buf +is NULL, +or +.I len +is less than zero; or for +.I type +8, the +.I level +is outside the range 1 to 8). +.TP +.B ENOSYS +This +.BR syslog () +system call is not available, because the kernel was compiled with the +.B CONFIG_PRINTK +kernel-configuration option disabled. +.TP +.B EPERM +An attempt was made to change +.I console_loglevel +or clear the kernel +message ring buffer by a process without sufficient privilege +(more precisely: without the +.B CAP_SYS_ADMIN +or +.B CAP_SYSLOG +capability). +.TP +.B ERESTARTSYS +System call was interrupted by a signal; nothing was read. +(This can be seen only during a trace.) +.SH STANDARDS +Linux. +.SH HISTORY +From the very start, people noted that it is unfortunate that +a system call and a library routine of the same name are entirely +different animals. +.\" In libc4 and libc5 the number of this call was defined by +.\" .BR SYS_klog . +.\" In glibc 2.0 the syscall is baptized +.\" .BR klogctl (). +.SH SEE ALSO +.BR dmesg (1), +.BR syslog (3), +.BR capabilities (7) |