[PATCH 0/3] syslog.2 updates

[PATCH 0/3] syslog.2 updates

[Jeremy Kerr]

Hi Michael,

I've discovered that the type=10 option to the syslog syscall isn't
documented, so I've done up a patch to add it in.

Also, I've done a small apostrophe fix, and completed the docs for
other vaules of the type argument.

Cheers,


Jeremy

[PATCH 3/3] syslog: document all type options

[Jeremy Kerr]

The type=6 and above options to syslog aren't documented, so
add a sentence about each.

Signed-off-by: Jeremy Kerr <jk-mnsaURCQ41sdnm+yROfE0A@public.gmane.org>

---

 man2/syslog.2 |   33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

Index: man-pages-2.77/man2/syslog.2
===================================================================
--- man-pages-2.77.orig/man2/syslog.2
+++ man-pages-2.77/man2/syslog.2
@@ -115,6 +115,39 @@ The call
 .RI (5, dummy , idummy )
 only executes the "clear ring buffer" command.
 
+The call
+.BR syslog ()
+.RI (6, dummy , dummy )
+sets the console log level to minimum, so that no messages are printed
+to the console.
+
+The call
+.BR syslog ()
+.RI (7, dummy , dummy )
+sets the console log level to default, so that messages are printed
+to the console.
+
+The call
+.BR syslog ()
+.RI (8, dummy , level )
+sets the console log level to
+.IR level .
+Which is an integer between 1 and 8 (inclusive).
+See the
+.B loglevel
+section for details.
+
+The call
+.BR syslog ()
+.RI (9, dummy , dummy )
+queries and returns the number of bytes currently available to be read
+on the kernel log buffer.
+
+The call
+.BR syslog ()
+.RI (10, dummy , dummy )
+queries and returns the total size of the kernel log buffer.
+
 .B The loglevel
 .br
 The kernel routine

Re: [PATCH 3/3] syslog: document all type options

[Michael Kerrisk]

Thanks Jeremy.  Applied for man-pages-2.79.

One comment below.

Jeremy Kerr wrote:
> The type=6 and above options to syslog aren't documented, so
> add a sentence about each.
> 
> Signed-off-by: Jeremy Kerr <jk-mnsaURCQ41sdnm+yROfE0A@public.gmane.org>
> 
> ---
> 
>  man2/syslog.2 |   33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
> 
> Index: man-pages-2.77/man2/syslog.2
> ===================================================================
> --- man-pages-2.77.orig/man2/syslog.2
> +++ man-pages-2.77/man2/syslog.2
> @@ -115,6 +115,39 @@ The call
>  .RI (5, dummy , idummy )
>  only executes the "clear ring buffer" command.
>  
> +The call
> +.BR syslog ()
> +.RI (6, dummy , dummy )

Here you are replicating a bad formatting glitch that I introduced a while
back when doing a semiautomated edit of this page a while back.

I reformatted these as simply

.I syslog(6,dummy,dummy)

etc.

Cheers,

Michael

> +sets the console log level to minimum, so that no messages are printed
> +to the console.
> +
> +The call
> +.BR syslog ()
> +.RI (7, dummy , dummy )
> +sets the console log level to default, so that messages are printed
> +to the console.
> +
> +The call
> +.BR syslog ()
> +.RI (8, dummy , level )
> +sets the console log level to
> +.IR level .
> +Which is an integer between 1 and 8 (inclusive).

I made that last piece:

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
> +.BR syslog ()
> +.RI (9, dummy , dummy )
> +queries and returns the number of bytes currently available to be read
> +on the kernel log buffer.
> +
> +The call
> +.BR syslog ()
> +.RI (10, dummy , dummy )
> +queries and returns the total size of the kernel log buffer.
> +
>  .B The loglevel
>  .br
>  The kernel routine
> 

-- 
Michael Kerrisk
Maintainer of the Linux man-pages project
http://www.kernel.org/doc/man-pages/
Want to report a man-pages bug?  Look here:
http://www.kernel.org/doc/man-pages/reporting_bugs.html

[PATCH 1/3] syslog: Add type 10

[Jeremy Kerr]

Since 2.6.6, we've had another type (10) option to the syslog syscall,
this change adds it to the syslog manpage.

Signed-off-by: Jeremy Kerr <jk-mnsaURCQ41sdnm+yROfE0A@public.gmane.org>

---

 man2/syslog.2 |    9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

Index: man-pages-2.77/man2/syslog.2
===================================================================
--- man-pages-2.77.orig/man2/syslog.2
+++ man-pages-2.77/man2/syslog.2
@@ -66,19 +66,20 @@ Quoting from
  *      7 \-\- Enable printk's 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.)
+Only functions 3 and 10 are allowed to non-root processes.
+(Function 9 was added in 2.4.10, function 10 in 2.6.6)
 
 .B The kernel log buffer
 .br
 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
+the size can be queried with function 10) in which messages given as
+argument to the kernel function
 .BR printk ()
 are stored
 (regardless of their loglevel).

Re: [PATCH 1/3] syslog: Add type 10

[Michael Kerrisk]

Hi Jeremy,

Jeremy Kerr wrote:
> Since 2.6.6, we've had another type (10) option to the syslog syscall,
> this change adds it to the syslog manpage.
> 
> Signed-off-by: Jeremy Kerr <jk-mnsaURCQ41sdnm+yROfE0A@public.gmane.org>
> 
> ---
> 
>  man2/syslog.2 |    9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> Index: man-pages-2.77/man2/syslog.2
> ===================================================================
> --- man-pages-2.77.orig/man2/syslog.2
> +++ man-pages-2.77/man2/syslog.2
> @@ -66,19 +66,20 @@ Quoting from
>   *      7 \-\- Enable printk's 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.)
> +Only functions 3 and 10 are allowed to non-root processes.

A nicely caught detail; confirmed.

> +(Function 9 was added in 2.4.10, function 10 in 2.6.6)

Version number confirmed.  Thanks for attending to that detail.

>  .B The kernel log buffer
>  .br
>  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
> +the size can be queried with function 10) in which messages given as
> +argument to the kernel function
>  .BR printk ()
>  are stored
>  (regardless of their loglevel).

Patch applied for man-pages-2.79.

But it seems to me that the piece on LOG_BUF_LEN was somewhat out of date.
 I reworked it as the following (could you confirm these details?):

===
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"
In recent kernels the size can be queried with command type 10.
===

Cheers,

Michael

-- 
Michael Kerrisk
Maintainer of the Linux man-pages project
http://www.kernel.org/doc/man-pages/
Want to report a man-pages bug?  Look here:
http://www.kernel.org/doc/man-pages/reporting_bugs.html

[PATCH 2/3] syslog: printk isn't posessive, or a contraction

[Jeremy Kerr]

.. so we don't need the apostrophe. We probably don't need the 's'
either.

Signed-off-by: Jeremy Kerr <jk-mnsaURCQ41sdnm+yROfE0A@public.gmane.org>

---

 man2/syslog.2 |    4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

Index: man-pages-2.77/man2/syslog.2
===================================================================
--- man-pages-2.77.orig/man2/syslog.2
+++ man-pages-2.77/man2/syslog.2
@@ -62,8 +62,8 @@ 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

Re: [PATCH 2/3] syslog: printk isn't posessive, or a contraction

[Michael Kerrisk]

Hi Jeremy,

Jeremy Kerr wrote:
> .. so we don't need the apostrophe. We probably don't need the 's'
> either.

Though as you are probably aware, this kind of use of apostrophes is not
uncommon.  It's one of those interesting gray areas of grammar: it is
derided by proscriptive grammarians, but turns up often in written English
when the writer feels uncomfortable about simply adding an "s" to create
the plural.  Here of course the original author (of the code comments,
taken from kernel/printk.c) wanted a plural but was (rightly) uncomfortable
about simply adding a character to what is a C identifier.

Still, I'm happy to apply your change, since the meaning remains clear, and
 makes the grammarians happy.

Applied for man-pages-2.79.

Cheers,

Michael

> 
> Signed-off-by: Jeremy Kerr <jk-mnsaURCQ41sdnm+yROfE0A@public.gmane.org>
> 
> ---
> 
>  man2/syslog.2 |    4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> Index: man-pages-2.77/man2/syslog.2
> ===================================================================
> --- man-pages-2.77.orig/man2/syslog.2
> +++ man-pages-2.77/man2/syslog.2
> @@ -62,8 +62,8 @@ 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
> 

-- 
Michael Kerrisk
Maintainer of the Linux man-pages project
http://www.kernel.org/doc/man-pages/
Want to report a man-pages bug?  Look here:
http://www.kernel.org/doc/man-pages/reporting_bugs.html

Re: [PATCH 0/3] syslog.2 updates

[Michael Kerrisk]

Jeremy Kerr wrote:
> Hi Michael,
> 
> I've discovered that the type=10 option to the syslog syscall isn't
> documented, so I've done up a patch to add it in.
> 
> Also, I've done a small apostrophe fix, and completed the docs for
> other vaules of the type argument.

Hi Jeremy,

Thanks for doing that, and for the nicely split patch set -- makes
processing so much easier!

Cheers,

Michael


-- 
Michael Kerrisk
Maintainer of the Linux man-pages project
http://www.kernel.org/doc/man-pages/
Want to report a man-pages bug?  Look here:
http://www.kernel.org/doc/man-pages/reporting_bugs.html