diff --git a/man2/syslog.2 b/man2/syslog.2 index 1a878103c..537e7ae3e 100644 --- a/man2/syslog.2 +++ b/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 -.TH SYSLOG 2 2007-06-01 "Linux" "Linux Programmer's Manual" +.\" 2008-02-15, Jeremy Kerr +.\" Add info on command type 10; add details on types 6, 7, 8, & 9. +.\" 2008-02-15, Michael Kerrisk +.\" 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.