mirror of https://github.com/mkerrisk/man-pages
Add info on command type 10.
Add details on types 6, 7, 8, and 9. Minor grammar fix. Update LOG_BUF_LEN details. Update RETURN VALUE section. Notes capability requirements under EPERM error. Other minor edits.
This commit is contained in:
Michael Kerrisk
parent
c33a62d8c1
commit
0527015d62
128
man2/syslog.2
128
man2/syslog.2
|
|
@ -21,7 +21,12 @@
|
|||
.\" the source, must acknowledge the copyright and authors of this work.
|
||||
.\"
|
||||
.\" Written 11 June 1995 by Andries Brouwer <aeb@cwi.nl>
|
||||
.TH SYSLOG 2 2007-06-01 "Linux" "Linux Programmer's Manual"
|
||||
.\" 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 2008-02-15 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
syslog, klogctl \- read and/or clear kernel message ring buffer;
|
||||
set console_loglevel
|
||||
|
|
@ -62,30 +67,33 @@ Quoting from
|
|||
* 3 \-\- Read up to the last 4k of messages in the ring buffer.
|
||||
* 4 \-\- Read and clear last 4k of messages in the ring buffer
|
||||
* 5 \-\- Clear ring buffer.
|
||||
* 6 \-\- Disable printk's to console
|
||||
* 7 \-\- Enable printk's to console
|
||||
* 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
|
||||
*/
|
||||
.fi
|
||||
|
||||
Only function 3 is allowed to non-root processes.
|
||||
(Function 9 was added in 2.4.10.)
|
||||
|
||||
.B The kernel log buffer
|
||||
.br
|
||||
Only command types 3 and 10 are allowed to non-root processes.
|
||||
Type 9 was added in 2.4.10; type 10 in 2.6.6.
|
||||
.SS The kernel log buffer
|
||||
The kernel has a cyclic buffer of length
|
||||
.B LOG_BUF_LEN
|
||||
(4096, since 1.3.54: 8192, since 2.1.113: 16384; in recent kernels
|
||||
the size can be set at compile time) in which messages given as argument
|
||||
to the kernel function
|
||||
in which messages given as arguments to the kernel function
|
||||
.BR printk ()
|
||||
are stored
|
||||
(regardless of their loglevel).
|
||||
are stored (regardless of their loglevel).
|
||||
In early kernels,
|
||||
.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"
|
||||
In recent kernels the size can be queried with command type 10.
|
||||
|
||||
The call
|
||||
.BR syslog ()
|
||||
.RI (2, buf , len )
|
||||
.I "syslog(2,buf,len)"
|
||||
waits until this kernel log buffer is nonempty, and then reads
|
||||
at most \fIlen\fP bytes into the buffer \fIbuf\fP.
|
||||
It returns
|
||||
|
|
@ -97,25 +105,53 @@ reads
|
|||
.IR /proc/kmsg .
|
||||
|
||||
The call
|
||||
.BR syslog ()
|
||||
.RI (3, buf , len )
|
||||
.I syslog(3,buf,len)
|
||||
will read the last \fIlen\fP bytes from the log buffer (non-destructively),
|
||||
but will not read more than was written into the buffer since the
|
||||
last "clear ring buffer" command (which does not clear the buffer at all).
|
||||
It returns the number of bytes read.
|
||||
|
||||
The call
|
||||
.BR syslog ()
|
||||
.RI (4, buf , len )
|
||||
.I syslog(4,buf,len)
|
||||
does precisely the same, but also executes the "clear ring buffer" command.
|
||||
|
||||
The call
|
||||
.BR syslog ()
|
||||
.RI (5, dummy , idummy )
|
||||
only executes the "clear ring buffer" command.
|
||||
.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.)
|
||||
|
||||
.B The loglevel
|
||||
.br
|
||||
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
|
||||
The kernel routine
|
||||
.BR printk ()
|
||||
will only print a message on the
|
||||
|
|
@ -127,11 +163,9 @@ This variable initially has the value
|
|||
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).
|
||||
This variable is set (to a value in the range 1-8) by the call
|
||||
.BR syslog ()
|
||||
.RI (8, dummy , value ).
|
||||
.IR syslog(8,dummy,value) .
|
||||
The calls
|
||||
.BR syslog ()
|
||||
.RI ( type , dummy , idummy )
|
||||
.I syslog(type,dummy,dummy)
|
||||
with \fItype\fP equal to 6 or 7, set it to 1 (kernel panics only)
|
||||
or 7 (all except debugging messages), respectively.
|
||||
|
||||
|
|
@ -156,20 +190,46 @@ as follows:
|
|||
#define KERN_DEBUG "<7>" /* debug-level messages */
|
||||
.fi
|
||||
.SH "RETURN VALUE"
|
||||
In case of error, \-1 is returned, and \fIerrno\fP is set.
|
||||
Otherwise,
|
||||
for \fItype\fP equal to 2, 3 or 4,
|
||||
For \fItype\fP equal to 2, 3, or 4, a successful call to
|
||||
.BR syslog ()
|
||||
returns the number
|
||||
of bytes read, and otherwise 0.
|
||||
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.
|
||||
|
||||
In case of error, \-1 is returned,
|
||||
and \fIerrno\fP is set to indicate the error.
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.B EINVAL
|
||||
Bad parameters.
|
||||
Bad parameters (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 EPERM
|
||||
An attempt was made to change console_loglevel or clear the kernel
|
||||
message ring buffer by a process without root permissions.
|
||||
message ring buffer by a process without root permissions
|
||||
(more precisely: without the
|
||||
.B CAP_SYS_ADMIN
|
||||
capability).
|
||||
.TP
|
||||
.B ERESTARTSYS
|
||||
System call was interrupted by a signal; nothing was read.
|
||||
|
|
|
|||
Loading…
Reference in New Issue