* [PATCH v2 2/2] man-pages: SYSLOG_ACTION_* constants are now exported
@ 2011-02-08 22:15 Paul Bolle
2011-02-08 22:32 ` Kees Cook
0 siblings, 1 reply; 3+ messages in thread
From: Paul Bolle @ 2011-02-08 22:15 UTC (permalink / raw
To: linux-kernel; +Cc: Kees Cook, David Woodhouse, Arnd Bergmann, mtk.manpages
The kernel now exports <linux/syslog.h>. This makes the SYSLOG_ACTION_*
constants available to userspace. This allows to replace the magic
numbers used in this man page with (what should be) more descriptive
names. The quote form kernel/printk.c can now also be dropped.
A few (more or less related) things were also fixed or changed:
- add a new sub section "The command types";
- the (userspace) buffer is called bufp everywhere (and not buf);
- add some whitespace to all call descriptions;
- use "ignored" in some call descriptions (instead of "dummy").
Signed-off-by: Paul Bolle <pebolle@tiscali.nl>
---
man2/syslog.2 | 110 +++++++++++++++++++++++++++------------------------------
1 files changed, 52 insertions(+), 58 deletions(-)
diff --git a/man2/syslog.2 b/man2/syslog.2
index fb018a6..9c4438b 100644
--- a/man2/syslog.2
+++ b/man2/syslog.2
@@ -38,6 +38,7 @@ set console_loglevel
/* The glibc interface */
.br
.B "#include <sys/klog.h>"
+.BR "#include <linux/syslog.h>" " /* For SYSLOG_ACTION_* constants */"
.sp
.BI "int klogctl(int " type ", char *" bufp ", int " len );
.fi
@@ -52,31 +53,6 @@ The system call of this name is about controlling the kernel
.IR printk ()
buffer, and the glibc version is called
.BR klogctl ().
-
-The \fItype\fP argument determines the action taken by this function.
-
-Quoting from
-.IR kernel/printk.c :
-.nf
-/*
- * Commands to sys_syslog:
- *
- * 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
- */
-.fi
-
-Only command types 3 and 10 are allowed to unprivileged 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
@@ -91,12 +67,32 @@ 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.
+Since kernel 2.6.6 the size can be queried with the
+\fBSYSLOG_ACTION_SIZE_BUFFER\fP command.
+.SS The command types
+The \fItype\fP argument determines the action taken by this function.
+Since kernel 2.6.34
+.IR <linux/syslog.h>
+defines these constants:
+
+.nf
+#define SYSLOG_ACTION_CLOSE 0 /* Currently a NOP. */
+#define SYSLOG_ACTION_OPEN 1 /* Currently a NOP. */
+#define SYSLOG_ACTION_READ 2
+#define SYSLOG_ACTION_READ_ALL 3
+#define SYSLOG_ACTION_READ_CLEAR 4
+#define SYSLOG_ACTION_CLEAR 5
+#define SYSLOG_ACTION_CONSOLE_OFF 6
+#define SYSLOG_ACTION_CONSOLE_ON 7
+#define SYSLOG_ACTION_CONSOLE_LEVEL 8
+#define SYSLOG_ACTION_SIZE_UNREAD 9
+#define SYSLOG_ACTION_SIZE_BUFFER 10
+.fi
The call
-.I "syslog(2,buf,len)"
+.I "syslog(SYSLOG_ACTION_READ, bufp, len)"
waits until this kernel log buffer is nonempty, and then reads
-at most \fIlen\fP bytes into the buffer \fIbuf\fP.
+at most \fIlen\fP bytes into the buffer \fIbufp\fP.
It returns
the number of bytes read.
Bytes read from the log disappear from
@@ -106,37 +102,34 @@ reads
.IR /proc/kmsg .
The call
-.I syslog(3,buf,len)
+.I syslog(SYSLOG_ACTION_READ_ALL, bufp, 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.
+last \fBSYSLOG_ACTION_CLEAR\fP command (which does not clear the buffer at
+all). It returns the number of bytes read. This call is allowed to
+unprivileged processes.
The call
-.I syslog(4,buf,len)
-does precisely the same, but also executes the "clear ring buffer" command.
+.I syslog(SYSLOG_ACTION_READ_CLEAR, bufp, len)
+does precisely the same, but also executes the \fBSYSLOG_ACTION_CLEAR\fP
+command.
The call
-.I syslog(5,dummy,dummy)
+.I syslog(SYSLOG_ACTION_CLEAR, ignored, ignored)
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)
+.I syslog(SYSLOG_ACTION_CONSOLE_OFF, ignored, ignored)
sets the console log level to minimum, so that no messages are printed
to the console.
The call
-.I syslog(7,dummy,dummy)
+.I syslog(SYSLOG_ACTION_CONSOLE_ON, ignored, ignored)
sets the console log level to default, so that messages are printed
to the console.
The call
-.I syslog(8,dummy,level)
+.I syslog(SYSLOG_ACTION_CONSOLE_LEVEL, ignored, level)
sets the console log level to
.IR level ,
which must be an integer between 1 and 8 (inclusive).
@@ -145,13 +138,14 @@ See the
section for details.
The call
-.I syslog(9,dummy,dummy)
+.I syslog(SYSLOG_ACTION_SIZE_UNREAD, ignored, ignored)
returns the number of bytes currently available to be read
-on the kernel log buffer.
+on the kernel log buffer. (This call was added in 2.4.10.)
The call
-.I syslog(10,dummy,dummy)
-returns the total size of the kernel log buffer.
+.I syslog(SYSLOG_ACTION_SIZE_BUFFER, ignored, ignored)
+returns the total size of the kernel log buffer. This call is allowed to
+unprivileged processes. (This call was added in 2.6.6.)
.SS The loglevel
The kernel routine
.BR printk ()
@@ -163,12 +157,10 @@ This variable initially has the value
(7), but is set to 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).
-This variable is set (to a value in the range 1-8) by the call
-.IR syslog(8,dummy,value) .
-The calls
-.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.
+This variable is set (to a value in the range 1-8) by the
+\fBSYSLOG_ACTION_CONSOLE_LEVEL\fP command. The \fBSYSLOG_ACTION_CONSOLE_OFF\fP
+command sets it to 1 (kernel panics only). The \fBSYSLOG_ACTION_CONSOLE_ON\fP
+command sets it to 7 (all messages except debugging messages).
Every text line in a message has its own loglevel.
This level is
@@ -191,15 +183,16 @@ as follows:
#define KERN_DEBUG "<7>" /* debug-level messages */
.fi
.SH "RETURN VALUE"
-For \fItype\fP equal to 2, 3, or 4, a successful call to
+For \fItype\fP \fBSYSLOG_ACTION_READ\fP, \fBSYSLOG_ACTION_READ_ALL\fP,
+or \fBSYSLOG_ACTION_READ_CLEAR\fP, a successful call to
.BR syslog ()
returns the number
of bytes read.
-For \fItype\fP 9,
+For \fItype\fP \fBSYSLOG_ACTION_SIZE_UNREAD\fP,
.BR syslog ()
returns the number of bytes currently
available to be read on the kernel log buffer.
-For \fItype\fP 10,
+For \fItype\fP \fBSYSLOG_ACTION_SIZE_BUFFER\fP,
.BR syslog ()
returns the total size of the kernel log buffer.
For other values of \fItype\fP, 0 is returned on success.
@@ -214,14 +207,15 @@ bad
.IR type ;
or for
.I type
-2, 3, or 4,
-.I buf
+\fBSYSLOG_ACTION_READ\fP, \fBSYSLOG_ACTION_READ_ALL\fP, or
+\fBSYSLOG_ACTION_READ_CLEAR\fP,
+.I bufp
is NULL,
or
.I len
is less than zero; or for
.I type
-8, the
+\fBSYSLOG_ACTION_CONSOLE_LEVEL\fP, the
.I level
is outside the range 1 to 8).
.TP
--
1.7.4
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH v2 2/2] man-pages: SYSLOG_ACTION_* constants are now exported
2011-02-08 22:15 [PATCH v2 2/2] man-pages: SYSLOG_ACTION_* constants are now exported Paul Bolle
@ 2011-02-08 22:32 ` Kees Cook
2011-02-09 3:26 ` Serge E. Hallyn
0 siblings, 1 reply; 3+ messages in thread
From: Kees Cook @ 2011-02-08 22:32 UTC (permalink / raw
To: Paul Bolle
Cc: linux-kernel, David Woodhouse, Arnd Bergmann, mtk.manpages,
Serge Hallyn
On Tue, Feb 08, 2011 at 11:15:34PM +0100, Paul Bolle wrote:
> The kernel now exports <linux/syslog.h>. This makes the SYSLOG_ACTION_*
> constants available to userspace. This allows to replace the magic
> numbers used in this man page with (what should be) more descriptive
> names. The quote form kernel/printk.c can now also be dropped.
>
> A few (more or less related) things were also fixed or changed:
> - add a new sub section "The command types";
> - the (userspace) buffer is called bufp everywhere (and not buf);
> - add some whitespace to all call descriptions;
> - use "ignored" in some call descriptions (instead of "dummy").
>
> Signed-off-by: Paul Bolle <pebolle@tiscali.nl>
Acked-by: Kees Cook <kees.cook@canonical.com>
As an aside, it might be a good idea to send an additional patch (since
it's logically separate from this) to update this portion of the man-page:
EPERM An attempt was made to change console_loglevel or clear the
kernel message ring buffer by a process without sufficient
privi lege (more precisely: without the CAP_SYS_ADMIN capability).
At least s/CAP_SYS_ADMIN/CAP_SYSLOG/, but probably include details about
which options are considered privileged.
Though that should probably go with including the description of CAP_SYSLOG
in the "capabilities" man-page.
-Kees
--
Kees Cook
Ubuntu Security Team
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH v2 2/2] man-pages: SYSLOG_ACTION_* constants are now exported
2011-02-08 22:32 ` Kees Cook
@ 2011-02-09 3:26 ` Serge E. Hallyn
0 siblings, 0 replies; 3+ messages in thread
From: Serge E. Hallyn @ 2011-02-09 3:26 UTC (permalink / raw
To: Kees Cook
Cc: Paul Bolle, linux-kernel, David Woodhouse, Arnd Bergmann,
mtk.manpages, Serge Hallyn
Quoting Kees Cook (kees.cook@canonical.com):
> On Tue, Feb 08, 2011 at 11:15:34PM +0100, Paul Bolle wrote:
> > The kernel now exports <linux/syslog.h>. This makes the SYSLOG_ACTION_*
> > constants available to userspace. This allows to replace the magic
> > numbers used in this man page with (what should be) more descriptive
> > names. The quote form kernel/printk.c can now also be dropped.
> >
> > A few (more or less related) things were also fixed or changed:
> > - add a new sub section "The command types";
> > - the (userspace) buffer is called bufp everywhere (and not buf);
> > - add some whitespace to all call descriptions;
> > - use "ignored" in some call descriptions (instead of "dummy").
> >
> > Signed-off-by: Paul Bolle <pebolle@tiscali.nl>
>
> Acked-by: Kees Cook <kees.cook@canonical.com>
>
>
> As an aside, it might be a good idea to send an additional patch (since
> it's logically separate from this) to update this portion of the man-page:
>
> EPERM An attempt was made to change console_loglevel or clear the
> kernel message ring buffer by a process without sufficient
> privi lege (more precisely: without the CAP_SYS_ADMIN capability).
>
> At least s/CAP_SYS_ADMIN/CAP_SYSLOG/, but probably include details about
> which options are considered privileged.
>
> Though that should probably go with including the description of CAP_SYSLOG
> in the "capabilities" man-page.
Thanks for the reminder, Kees. Michael, I'll try to get an update for
capabilities.7 to you soon.
-serge
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2011-02-09 3:26 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2011-02-08 22:15 [PATCH v2 2/2] man-pages: SYSLOG_ACTION_* constants are now exported Paul Bolle
2011-02-08 22:32 ` Kees Cook
2011-02-09 3:26 ` Serge E. Hallyn
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.