newsyslog.8 - patch to improve man page

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

newsyslog.8 - patch to improve man page

Ingo Schwarze
Hi,

the attached patch is intended to improve the following aspects
of the usr.bin/newsyslog/newsyslog.8 man page, CVS rev. 1.41.

 1) I wondered whether i might specify "0" in the size field
    in order to achieve an effect similar to the -F option,
    but for a single log file only.
    Apparently, this is not the case.  In the size field, "0"
    acts just like "*".  I checked this by both reading the
    source code and by testing the newsyslog binary.

 2) When reading the source, i noticed that the MIN_SIZE #define
    is used together with the "when" field only, but not at all
    together with the "size" field.  Thus, i suggest to move its
    explanation to the apropriate paragraph and to slightly modify
    the wording accordingly.

 3) The man page correctly states that MIN_SIZE is not used with
    log files marked as "binary".  At this point, it might be
    useful to add that the -F option does not only overrule the
    "size" and "when" fields, but also the MIN_SIZE #define.  Note
    this is not yet perfectly clear from the explanation of the -F
    option reading "regardless of the size and/or age requirements
    specified in /etc/newsyslog.conf" - MIN_SIZE is not specified
    in /etc/newsyslog.conf.
    I checked that -F does indeed overrule MIN_SIZE by both reading
    the source code and by testing the binary.

 4) There is one trivial typo:
    'The empty string "" can use used to prevent .Nm from...'

Additional rationale:
All this is actually relevant when you intend to *always* rotate all
logs at well-defined times, even when nearly empty.  This may make
sense when you intend to automatically collect, analyse and archive
them, in my case to a different machine.  Logs not being rotated
may easily generate spurious warnings in such a scenario.
Currently, i am setting _both_ "size" and "when" to "*" and
i am running newsyslog with the -F option.

Thanks for your time and consideration (and for the fine OS!),
  Ingo

--
Ingo Schwarze <[hidden email]>
UStA Uni Karlsruhe, Germany

 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----

--- newsyslog.8-1.41 Wed Nov 30 12:18:27 2005
+++ newsyslog.8 Mon May 22 23:56:10 2006
@@ -201,20 +201,14 @@
 .It Ar count
 The number of archives to be kept besides the log file itself.
 .It Ar size
-When the size of the log file (in kilobytes) reaches this point, the log
+When this number is greater than 0 and
+the size of the log file (in kilobytes) reaches this point, the log
 file is trimmed as described above.
 If this field is replaced by an
 .Ql \&* ,
 then the size of
 the log file is not taken into account when determining when to trim the
 log file.
-By default, files smaller than 512 bytes are not rotated unless the
-.Sq B
-(binary) flag is set.
-This prevents
-.Nm
-from rotating files consisting solely of a message indicating
-that the log file has been turned over.
 .It Ar when
 The
 .Ar when
@@ -251,6 +245,17 @@
 component in the current implementation, since the only comparison is
 .Sq within the hour .
 .Pp
+Even when their time has come, files smaller than 512 bytes are not
+rotated unless the
+.Sq B
+(binary) flag is set or the
+.Fl F
+(force) option is specified.
+This prevents
+.Nm
+from rotating files consisting solely of a message indicating
+that the log file has been turned over.
+.Pp
 .Sy ISO 8601 restricted time format:
 The lead-in character for a restricted
 .Tn ISO 8601
@@ -406,7 +411,7 @@
 .Pq Ql \&" .
 The empty string,
 .Ql \&"\&" ,
-can use used to prevent
+can be used to prevent
 .Nm
 from sending a signal or running a command.
 You cannot specify both a command and a PID file.

Reply | Threaded
Open this post in threaded view
|

Re: newsyslog.8 - patch to improve man page

Jason McIntyre-2
On Tue, May 23, 2006 at 01:13:49AM +0200, Ingo Schwarze wrote:

> Hi,
>
> the attached patch is intended to improve the following aspects
> of the usr.bin/newsyslog/newsyslog.8 man page, CVS rev. 1.41.
>
>  1) I wondered whether i might specify "0" in the size field
>     in order to achieve an effect similar to the -F option,
>     but for a single log file only.
>     Apparently, this is not the case.  In the size field, "0"
>     acts just like "*".  I checked this by both reading the
>     source code and by testing the newsyslog binary.
>

i guess for exactness' sake, we could document what happens when size is
set to 0.

>  2) When reading the source, i noticed that the MIN_SIZE #define
>     is used together with the "when" field only, but not at all
>     together with the "size" field.  Thus, i suggest to move its
>     explanation to the apropriate paragraph and to slightly modify
>     the wording accordingly.
>

this one i don;t like: why is it relevant to the "when" field that
files < 512 are not rotated? the section documenting "size" seems
correct.

>  3) The man page correctly states that MIN_SIZE is not used with
>     log files marked as "binary".  At this point, it might be
>     useful to add that the -F option does not only overrule the
>     "size" and "when" fields, but also the MIN_SIZE #define.  Note
>     this is not yet perfectly clear from the explanation of the -F
>     option reading "regardless of the size and/or age requirements
>     specified in /etc/newsyslog.conf" - MIN_SIZE is not specified
>     in /etc/newsyslog.conf.
>     I checked that -F does indeed overrule MIN_SIZE by both reading
>     the source code and by testing the binary.
>

i don;t know if this bit is needed either, but it could go in for
completeness' sake.

>  4) There is one trivial typo:
>     'The empty string "" can use used to prevent .Nm from...'
>

agreed.

> Additional rationale:
> All this is actually relevant when you intend to *always* rotate all
> logs at well-defined times, even when nearly empty.  This may make
> sense when you intend to automatically collect, analyse and archive
> them, in my case to a different machine.  Logs not being rotated
> may easily generate spurious warnings in such a scenario.
> Currently, i am setting _both_ "size" and "when" to "*" and
> i am running newsyslog with the -F option.
>

hmm, if you're running with -F, why set these fields?

jmc

Reply | Threaded
Open this post in threaded view
|

Re: newsyslog.8 - patch to improve man page

Jason McIntyre-2
In reply to this post by Ingo Schwarze
On Tue, May 23, 2006 at 01:13:49AM +0200, Ingo Schwarze wrote:
>
> the attached patch is intended to improve the following aspects
> of the usr.bin/newsyslog/newsyslog.8 man page, CVS rev. 1.41.
>

in the end i committed the following:

Index: newsyslog.8
===================================================================
RCS file: /cvs/src/usr.bin/newsyslog/newsyslog.8,v
retrieving revision 1.41
diff -u -r1.41 newsyslog.8
--- newsyslog.8 30 Nov 2005 11:18:27 -0000 1.41
+++ newsyslog.8 23 May 2006 19:24:57 -0000
@@ -204,13 +204,17 @@
 When the size of the log file (in kilobytes) reaches this point, the log
 file is trimmed as described above.
 If this field is replaced by an
-.Ql \&* ,
+.Ql * ,
+or set to
+.Ql 0 ,
 then the size of
 the log file is not taken into account when determining when to trim the
 log file.
 By default, files smaller than 512 bytes are not rotated unless the
 .Sq B
-(binary) flag is set.
+(binary) flag is set or the
+.Fl F
+option is specified.
 This prevents
 .Nm
 from rotating files consisting solely of a message indicating
@@ -406,7 +410,7 @@
 .Pq Ql \&" .
 The empty string,
 .Ql \&"\&" ,
-can use used to prevent
+can be used to prevent
 .Nm
 from sending a signal or running a command.
 You cannot specify both a command and a PID file.

thanks for the diff
jmc