mirror of https://github.com/mkerrisk/man-pages
syslog.2: Substantially reorganize discussion of commands
Make the layout if the discussion of the commands more readable. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
9f924d1702
commit
1850e19a35
184
man2/syslog.2
184
man2/syslog.2
|
@ -52,13 +52,28 @@ The system call of this name is about controlling the kernel
|
||||||
.IR printk ()
|
.IR printk ()
|
||||||
buffer, and the glibc wrapper function is called
|
buffer, and the glibc wrapper function is called
|
||||||
.BR klogctl ().
|
.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 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"
|
||||||
|
.\" For 2.6, precisely the option seems to have appeared in 2.5.55.
|
||||||
|
In recent kernels 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 \fItype\fP argument determines the action taken by this function.
|
||||||
The list below specifies the values for
|
The list below specifies the values for
|
||||||
.IR type .
|
.IR type .
|
||||||
The symbolic names are defined in the kernel source,
|
The symbolic names are defined in the kernel source,
|
||||||
but are not exported to user space;
|
but are not exported to user space;
|
||||||
you will either need to use the numbers, or define the names yourself.)
|
you will either need to use the numbers, or define the names yourself.
|
||||||
.TP
|
.TP
|
||||||
.BR SYSLOG_ACTION_CLOSE " (0)"
|
.BR SYSLOG_ACTION_CLOSE " (0)"
|
||||||
Close the log. Currently a NOP.
|
Close the log. Currently a NOP.
|
||||||
|
@ -68,34 +83,87 @@ Open the log. Currently a NOP.
|
||||||
.TP
|
.TP
|
||||||
.BR SYSLOG_ACTION_READ " (2)"
|
.BR SYSLOG_ACTION_READ " (2)"
|
||||||
Read from the log.
|
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 only be read once.
|
||||||
|
This is the function executed by the kernel when a user program reads
|
||||||
|
.IR /proc/kmsg .
|
||||||
.TP
|
.TP
|
||||||
.BR SYSLOG_ACTION_READ_ALL " (3)"
|
.BR SYSLOG_ACTION_READ_ALL " (3)"
|
||||||
Read all messages remaining in the ring buffer.
|
Read all messages remaining in the ring buffer.
|
||||||
|
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 (which does not clear the buffer at all).
|
||||||
|
The call returns the number of bytes read.
|
||||||
.TP
|
.TP
|
||||||
.BR SYSLOG_ACTION_READ_CLEAR " (4)"
|
.BR SYSLOG_ACTION_READ_CLEAR " (4)"
|
||||||
Read and clear all messages remaining in the ring buffer
|
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
|
.TP
|
||||||
.BR SYSLOG_ACTION_CLEAR " (5)"
|
.BR SYSLOG_ACTION_CLEAR " (5)"
|
||||||
Clear ring buffer.
|
The call executes just the "clear ring buffer" command.
|
||||||
|
The
|
||||||
|
.I bufp
|
||||||
|
and
|
||||||
|
.I len
|
||||||
|
arguments are ignored.
|
||||||
.TP
|
.TP
|
||||||
.BR SYSLOG_ACTION_CONSOLE_OFF " (6)"
|
.BR SYSLOG_ACTION_CONSOLE_OFF " (6)"
|
||||||
Disable printk to console
|
Disable printk to console.
|
||||||
|
The call sets the console log level to the minimum,
|
||||||
|
so that no messages are printed to the console.
|
||||||
|
The
|
||||||
|
.I bufp
|
||||||
|
and
|
||||||
|
.I len
|
||||||
|
arguments are ignored.
|
||||||
.TP
|
.TP
|
||||||
.BR SYSLOG_ACTION_CONSOLE_ON " (7)"
|
.BR SYSLOG_ACTION_CONSOLE_ON " (7)"
|
||||||
Enable printk to console
|
The call sets the console log level to the default,
|
||||||
|
so that messages are printed to the console.
|
||||||
|
The
|
||||||
|
.I bufp
|
||||||
|
and
|
||||||
|
.I len
|
||||||
|
arguments are ignored.
|
||||||
.TP
|
.TP
|
||||||
.BR SYSLOG_ACTION_CONSOLE_LEVEL " (8)"
|
.BR SYSLOG_ACTION_CONSOLE_LEVEL " (8)"
|
||||||
Set level of messages printed to console
|
The call sets the console log level to the value given in
|
||||||
|
.IR len ,
|
||||||
|
which must be an integer between 1 and 8 (inclusive).
|
||||||
|
See the
|
||||||
|
.B loglevel
|
||||||
|
section for details.
|
||||||
|
The
|
||||||
|
.I bufp
|
||||||
|
argument is ignored.
|
||||||
.TP
|
.TP
|
||||||
.BR SYSLOG_ACTION_SIZE_UNREAD " (9)"
|
.BR SYSLOG_ACTION_SIZE_UNREAD " (9) (since Linux 2.4.10)"
|
||||||
Return number of unread characters in the log buffer
|
The call
|
||||||
|
returns the number of bytes currently available to be read
|
||||||
|
on the kernel log buffer.
|
||||||
|
The
|
||||||
|
.I bufp
|
||||||
|
and
|
||||||
|
.I len
|
||||||
|
arguments are ignored.
|
||||||
.TP
|
.TP
|
||||||
.BR SYSLOG_ACTION_SIZE_BUFFER " (10)"
|
.BR SYSLOG_ACTION_SIZE_BUFFER " (10) (since Linux 2.6.6)"
|
||||||
Return size of the log buffer
|
This command returns the total size of the kernel log buffer.
|
||||||
|
The
|
||||||
|
.I bufp
|
||||||
|
and
|
||||||
|
.I len
|
||||||
|
arguments are ignored.
|
||||||
.fi
|
.fi
|
||||||
.PP
|
.PP
|
||||||
Type 9 was added in Linux 2.4.10; type 10 in Linux 2.6.6.
|
|
||||||
|
|
||||||
All commands except 3 and 10 require privilege.
|
All commands except 3 and 10 require privilege.
|
||||||
In Linux kernels before 2.6.37,
|
In Linux kernels before 2.6.37,
|
||||||
command types 3 and 10 are allowed to unprivileged processes;
|
command types 3 and 10 are allowed to unprivileged processes;
|
||||||
|
@ -112,81 +180,6 @@ Since Linux 2.6.37,
|
||||||
capability (now deprecated for this purpose) or the (new)
|
capability (now deprecated for this purpose) or the (new)
|
||||||
.BR CAP_SYSLOG
|
.BR CAP_SYSLOG
|
||||||
capability.
|
capability.
|
||||||
.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 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"
|
|
||||||
.\" For 2.6, precisely the option seems to have appeared in 2.5.55.
|
|
||||||
In recent kernels the size can be queried with command type 10.
|
|
||||||
|
|
||||||
The call
|
|
||||||
.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
|
|
||||||
the number of bytes read.
|
|
||||||
Bytes read from the log disappear from
|
|
||||||
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
|
|
||||||
.I syslog(3,buf,len)
|
|
||||||
will read 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 (which does not clear the buffer at all).
|
|
||||||
It returns the number of bytes read.
|
|
||||||
|
|
||||||
The call
|
|
||||||
.I syslog(4,buf,len)
|
|
||||||
does precisely the same, but also executes the "clear ring buffer" command.
|
|
||||||
|
|
||||||
The call
|
|
||||||
.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.)
|
|
||||||
|
|
||||||
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
|
.SS The loglevel
|
||||||
The kernel routine
|
The kernel routine
|
||||||
.BR printk ()
|
.BR printk ()
|
||||||
|
@ -198,11 +191,16 @@ This variable initially has the value
|
||||||
(7), but is set to 10 if the
|
(7), but is set to 10 if the
|
||||||
kernel command line contains the word "debug", and to 15 in case
|
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).
|
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
|
This variable is set (to a value in the range 1-8) by a
|
||||||
.IR syslog(8,dummy,value) .
|
.BR syslog ()
|
||||||
The calls
|
call with a
|
||||||
.I syslog(type,dummy,dummy)
|
.I type
|
||||||
with \fItype\fP equal to 6 or 7, set it to 1 (kernel panics only)
|
of 8.
|
||||||
|
Calls to
|
||||||
|
.BR syslog ()
|
||||||
|
with
|
||||||
|
.I type
|
||||||
|
equal to 6 or 7 set the variable to 1 (kernel panics only)
|
||||||
or 7 (all except debugging messages), respectively.
|
or 7 (all except debugging messages), respectively.
|
||||||
|
|
||||||
Every text line in a message has its own loglevel.
|
Every text line in a message has its own loglevel.
|
||||||
|
|
Loading…
Reference in New Issue