2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl)
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" Written 11 June 1995 by Andries Brouwer <aeb@cwi.nl>
|
2008-02-14 10:32:04 +00:00
|
|
|
.\" 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.
|
2008-03-03 13:24:34 +00:00
|
|
|
.\"
|
2011-09-08 01:31:45 +00:00
|
|
|
.TH SYSLOG 2 2011-09-07 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
2007-04-12 22:42:49 +00:00
|
|
|
syslog, klogctl \- read and/or clear kernel message ring buffer;
|
2006-12-27 03:54:41 +00:00
|
|
|
set console_loglevel
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
2007-05-26 15:22:28 +00:00
|
|
|
.BI "int syslog(int " type ", char *" bufp ", int " len );
|
2008-01-12 08:57:58 +00:00
|
|
|
.B " /* No wrapper provided in glibc */"
|
2007-05-26 15:22:28 +00:00
|
|
|
.sp
|
2004-11-03 13:51:07 +00:00
|
|
|
/* The glibc interface */
|
|
|
|
.br
|
|
|
|
.B "#include <sys/klog.h>"
|
|
|
|
.sp
|
|
|
|
.BI "int klogctl(int " type ", char *" bufp ", int " len );
|
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
2008-12-05 20:47:53 +00:00
|
|
|
If you need the C library function
|
2007-05-26 15:22:28 +00:00
|
|
|
.BR syslog ()
|
|
|
|
(which talks to
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR syslogd (8)),
|
|
|
|
then look at
|
|
|
|
.BR syslog (3).
|
|
|
|
The system call of this name is about controlling the kernel
|
2005-10-19 07:07:02 +00:00
|
|
|
.IR printk ()
|
2011-09-08 01:31:45 +00:00
|
|
|
buffer, and the glibc wrapper function is called
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR klogctl ().
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2011-09-08 01:31:45 +00:00
|
|
|
The \fItype\fP argument determines the action taken by this function,
|
|
|
|
as follows:
|
2004-11-03 13:51:07 +00:00
|
|
|
|
|
|
|
.nf
|
2011-09-08 01:31:45 +00:00
|
|
|
0 \-\- Close the log. Currently a NOP.
|
|
|
|
1 \-\- Open the log. Currently a NOP.
|
|
|
|
2 \-\- Read from the log.
|
|
|
|
3 \-\- Read all messages remaining in the ring buffer.
|
|
|
|
4 \-\- Read and clear all messages remaining in the ring buffer
|
|
|
|
5 \-\- Clear ring buffer.
|
|
|
|
6 \-\- Disable printk to console
|
|
|
|
7 \-\- Enable printk to console
|
|
|
|
8 \-\- Set level of messages printed to console
|
|
|
|
9 \-\- Return number of unread characters in the log buffer
|
|
|
|
10 \-\- Return size of the log buffer
|
2004-11-03 13:51:07 +00:00
|
|
|
.fi
|
|
|
|
|
2011-09-08 01:31:45 +00:00
|
|
|
Type 9 was added in Linux 2.4.10; type 10 in Linux 2.6.6.
|
|
|
|
|
2011-09-08 01:33:42 +00:00
|
|
|
In Linux kernels before 2.6.37,
|
|
|
|
only command types 3 and 10 are allowed to unprivileged processes.
|
|
|
|
Since Linux 2.6.37,
|
|
|
|
command types 3 and 10 are only allowed to unprivileged processes if
|
|
|
|
.IR /proc/sys/kernel/dmesg_restrict
|
|
|
|
has the value 0.
|
|
|
|
Before Linux 2.6.37, "privileged" means that the caller has the
|
|
|
|
.BR CAP_SYS_ADMIN
|
|
|
|
capability.
|
|
|
|
Since Linux 2.6.37,
|
|
|
|
"privileged" means that the caller has either the
|
|
|
|
.BR CAP_SYS_ADMIN
|
|
|
|
capability (now deprecated for this purpose) or the (new)
|
|
|
|
.BR CAP_SYSLOG
|
|
|
|
capability.
|
2008-02-14 10:32:04 +00:00
|
|
|
.SS The kernel log buffer
|
2007-12-16 13:10:53 +00:00
|
|
|
The kernel has a cyclic buffer of length
|
|
|
|
.B LOG_BUF_LEN
|
2008-02-14 10:32:04 +00:00
|
|
|
in which messages given as arguments to the kernel function
|
2007-05-12 13:12:02 +00:00
|
|
|
.BR printk ()
|
2008-02-14 10:32:04 +00:00
|
|
|
are stored (regardless of their loglevel).
|
2008-03-03 13:24:34 +00:00
|
|
|
In early kernels,
|
2008-02-14 10:32:04 +00:00
|
|
|
.B LOG_BUF_LEN
|
|
|
|
had the value 4096;
|
|
|
|
from kernel 1.3.54, it was 8192;
|
|
|
|
from kernel 2.1.113 it was 16384;
|
|
|
|
since 2.4.23/2.6 the value is a kernel configuration option.
|
|
|
|
.\" Under "General setup" ==> "Kernel log buffer size"
|
2008-02-14 15:04:20 +00:00
|
|
|
.\" For 2.6, precisely the option seems to have appeared in 2.5.55.
|
2008-02-14 10:32:04 +00:00
|
|
|
In recent kernels the size can be queried with command type 10.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
|
|
|
The call
|
2008-02-14 10:32:04 +00:00
|
|
|
.I "syslog(2,buf,len)"
|
mbind.2, rename.2, sched_setscheduler.2, set_mempolicy.2, syslog.2, argz_add.3, dlopen.3, scanf.3, strtod.3, strtok.3, tcgetpgrp.3, hd.4, cpuset.7, regex.7, ld.so.8: Global fix: s/non-empty/nonempty/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:41:47 +00:00
|
|
|
waits until this kernel log buffer is nonempty, and then reads
|
2007-04-12 22:42:49 +00:00
|
|
|
at most \fIlen\fP bytes into the buffer \fIbuf\fP.
|
|
|
|
It returns
|
|
|
|
the number of bytes read.
|
|
|
|
Bytes read from the log disappear from
|
2004-11-03 13:51:07 +00:00
|
|
|
the log buffer: the information can only be read once.
|
|
|
|
This is the function executed by the kernel when a user program
|
|
|
|
reads
|
|
|
|
.IR /proc/kmsg .
|
|
|
|
|
|
|
|
The call
|
2008-02-14 10:32:04 +00:00
|
|
|
.I syslog(3,buf,len)
|
accept.2, access.2, acct.2, clock_nanosleep.2, mbind.2, mincore.2, remap_file_pages.2, sched_setscheduler.2, set_mempolicy.2, splice.2, stat.2, syslog.2, timer_create.2, timerfd_create.2, truncate.2, fenv.3, ferror.3, fflush.3, fgetwc.3, fgetws.3, flockfile.3, fputwc.3, fputws.3, fread.3, getopt.3, gets.3, getwchar.3, glob.3, iconv.3, longjmp.3, pow.3, printf.3, puts.3, putwchar.3, regex.3, rpc.3, scanf.3, setjmp.3, termios.3, unlocked_stdio.3, wcswidth.3, hd.4, rtc.4, st.4, core.5, dir_colors.5, elf.5, proc.5, arp.7, ascii.7, boot.7, bootparam.7, charsets.7, futex.7, ip.7, iso_8859-11.7, man-pages.7, man.7, mdoc.samples.7, path_resolution.7, pipe.7, posixoptions.7, unicode.7, unix.7, uri.7, utf-8.7, ld.so.8: s/non-/non/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 17:20:12 +00:00
|
|
|
will read the last \fIlen\fP bytes from the log buffer (nondestructively),
|
2004-11-03 13:51:07 +00:00
|
|
|
but will not read more than was written into the buffer since the
|
2007-12-18 07:47:22 +00:00
|
|
|
last "clear ring buffer" command (which does not clear the buffer at all).
|
2004-11-03 13:51:07 +00:00
|
|
|
It returns the number of bytes read.
|
|
|
|
|
|
|
|
The call
|
2008-02-14 10:32:04 +00:00
|
|
|
.I syslog(4,buf,len)
|
2007-12-18 07:47:22 +00:00
|
|
|
does precisely the same, but also executes the "clear ring buffer" command.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
|
|
|
The call
|
2008-02-14 10:32:04 +00:00
|
|
|
.I syslog(5,dummy,dummy)
|
|
|
|
executes just the "clear ring buffer" command.
|
|
|
|
(In each call where
|
|
|
|
.I buf
|
|
|
|
or
|
|
|
|
.I len
|
|
|
|
is shown as "dummy", the value of the argument is ignored by the call.)
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2008-02-14 10:32:04 +00:00
|
|
|
The call
|
|
|
|
.I syslog(6,dummy,dummy)
|
|
|
|
sets the console log level to minimum, so that no messages are printed
|
|
|
|
to the console.
|
|
|
|
|
|
|
|
The call
|
|
|
|
.I syslog(7,dummy,dummy)
|
|
|
|
sets the console log level to default, so that messages are printed
|
|
|
|
to the console.
|
|
|
|
|
|
|
|
The call
|
|
|
|
.I syslog(8,dummy,level)
|
|
|
|
sets the console log level to
|
|
|
|
.IR level ,
|
|
|
|
which must be an integer between 1 and 8 (inclusive).
|
|
|
|
See the
|
|
|
|
.B loglevel
|
|
|
|
section for details.
|
|
|
|
|
|
|
|
The call
|
|
|
|
.I syslog(9,dummy,dummy)
|
|
|
|
returns the number of bytes currently available to be read
|
|
|
|
on the kernel log buffer.
|
|
|
|
|
|
|
|
The call
|
|
|
|
.I syslog(10,dummy,dummy)
|
|
|
|
returns the total size of the kernel log buffer.
|
|
|
|
.SS The loglevel
|
2007-05-12 13:12:02 +00:00
|
|
|
The kernel routine
|
|
|
|
.BR printk ()
|
|
|
|
will only print a message on the
|
2004-11-03 13:51:07 +00:00
|
|
|
console, if it has a loglevel less than the value of the variable
|
2005-07-06 06:54:27 +00:00
|
|
|
.IR console_loglevel .
|
2007-12-16 13:10:53 +00:00
|
|
|
This variable initially has the value
|
|
|
|
.B DEFAULT_CONSOLE_LOGLEVEL
|
|
|
|
(7), but is set to 10 if the
|
2007-12-18 07:47:22 +00:00
|
|
|
kernel command line contains the word "debug", and to 15 in case
|
2005-07-06 06:54:27 +00:00
|
|
|
of a kernel fault (the 10 and 15 are just silly, and equivalent to 8).
|
2004-11-03 13:51:07 +00:00
|
|
|
This variable is set (to a value in the range 1-8) by the call
|
2008-02-14 10:32:04 +00:00
|
|
|
.IR syslog(8,dummy,value) .
|
2004-11-03 13:51:07 +00:00
|
|
|
The calls
|
2008-02-14 10:32:04 +00:00
|
|
|
.I syslog(type,dummy,dummy)
|
2004-11-03 13:51:07 +00:00
|
|
|
with \fItype\fP equal to 6 or 7, set it to 1 (kernel panics only)
|
|
|
|
or 7 (all except debugging messages), respectively.
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
Every text line in a message has its own loglevel.
|
|
|
|
This level is
|
2007-12-16 13:10:53 +00:00
|
|
|
.I "DEFAULT_MESSAGE_LOGLEVEL \- 1"
|
|
|
|
(6) unless the line starts with <d>
|
2004-11-03 13:51:07 +00:00
|
|
|
where \fId\fP is a digit in the range 1-7, in which case the level
|
2007-04-12 22:42:49 +00:00
|
|
|
is \fId\fP.
|
|
|
|
The conventional meaning of the loglevel is defined in
|
2004-11-03 13:51:07 +00:00
|
|
|
.I <linux/kernel.h>
|
|
|
|
as follows:
|
|
|
|
|
|
|
|
.nf
|
|
|
|
#define KERN_EMERG "<0>" /* system is unusable */
|
|
|
|
#define KERN_ALERT "<1>" /* action must be taken immediately */
|
|
|
|
#define KERN_CRIT "<2>" /* critical conditions */
|
|
|
|
#define KERN_ERR "<3>" /* error conditions */
|
|
|
|
#define KERN_WARNING "<4>" /* warning conditions */
|
|
|
|
#define KERN_NOTICE "<5>" /* normal but significant condition */
|
|
|
|
#define KERN_INFO "<6>" /* informational */
|
|
|
|
#define KERN_DEBUG "<7>" /* debug-level messages */
|
|
|
|
.fi
|
|
|
|
.SH "RETURN VALUE"
|
2008-02-14 10:32:04 +00:00
|
|
|
For \fItype\fP equal to 2, 3, or 4, a successful call to
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR syslog ()
|
|
|
|
returns the number
|
2008-02-14 10:32:04 +00:00
|
|
|
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 ()
|
2008-04-24 09:36:45 +00:00
|
|
|
returns the total size of the kernel log buffer.
|
2008-02-14 10:32:04 +00:00
|
|
|
For other values of \fItype\fP, 0 is returned on success.
|
|
|
|
|
|
|
|
In case of error, \-1 is returned,
|
|
|
|
and \fIerrno\fP is set to indicate the error.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
2008-07-10 20:53:08 +00:00
|
|
|
Bad arguments (e.g.,
|
2008-02-14 10:32:04 +00:00
|
|
|
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).
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2010-11-01 06:18:03 +00:00
|
|
|
.B ENOSYS
|
|
|
|
This
|
|
|
|
.BR syslog ()
|
|
|
|
system call is not available, because the kernel was compiled with the
|
|
|
|
.BR CONFIG_PRINTK
|
|
|
|
kernel-configuration option disabled.
|
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EPERM
|
|
|
|
An attempt was made to change console_loglevel or clear the kernel
|
2008-04-29 13:45:56 +00:00
|
|
|
message ring buffer by a process without sufficient privilege
|
2008-02-14 10:32:04 +00:00
|
|
|
(more precisely: without the
|
|
|
|
.B CAP_SYS_ADMIN
|
2011-09-08 01:33:42 +00:00
|
|
|
or
|
|
|
|
.BR CAP_SYSLOG
|
2008-02-14 10:32:04 +00:00
|
|
|
capability).
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B ERESTARTSYS
|
2005-07-06 06:54:27 +00:00
|
|
|
System call was interrupted by a signal; nothing was read.
|
2004-11-03 13:51:07 +00:00
|
|
|
(This can be seen only during a trace.)
|
|
|
|
.SH "CONFORMING TO"
|
2007-12-25 21:28:09 +00:00
|
|
|
This system call is Linux-specific and should not be used in programs
|
2004-11-03 13:51:07 +00:00
|
|
|
intended to be portable.
|
|
|
|
.SH NOTES
|
|
|
|
From the very start people noted that it is unfortunate that
|
2007-06-28 19:06:57 +00:00
|
|
|
a system call and a library routine of the same name are entirely
|
2004-11-03 13:51:07 +00:00
|
|
|
different animals.
|
|
|
|
In libc4 and libc5 the number of this call was defined by
|
|
|
|
.BR SYS_klog .
|
2007-06-08 09:56:56 +00:00
|
|
|
In glibc 2.0 the syscall is baptized
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR klogctl ().
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
2011-09-08 01:33:42 +00:00
|
|
|
.BR syslog (3),
|
|
|
|
.BR capabilities (7)
|