===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/newsyslog/newsyslog.8,v
retrieving revision 1.32
retrieving revision 1.33
diff -c -r1.32 -r1.33
*** src/usr.bin/newsyslog/newsyslog.8	2003/02/09 07:26:45	1.32
--- src/usr.bin/newsyslog/newsyslog.8	2003/02/12 19:17:36	1.33
***************
*** 1,4 ****
! .\"	$OpenBSD: newsyslog.8,v 1.32 2003/02/09 07:26:45 jmc Exp $
  .\"
  .\" Copyright (c) 1997, Jason Downs.  All rights reserved.
  .\"
--- 1,4 ----
! .\"	$OpenBSD: newsyslog.8,v 1.33 2003/02/12 19:17:36 millert Exp $
  .\"
  .\" Copyright (c) 1997, Jason Downs.  All rights reserved.
  .\"
***************
*** 77,83 ****
  has the next to last
  period's logs in it, and so on, up to a user-specified number of
  archived logs.
! Optionally the archived logs can be compressed to save space.
  .Pp
  The options are as follows:
  .Bl -tag -width Ds
--- 77,83 ----
  has the next to last
  period's logs in it, and so on, up to a user-specified number of
  archived logs.
! The archived logs may be optionally compressed to save space.
  .Pp
  The options are as follows:
  .Bl -tag -width Ds
***************
*** 116,122 ****
  .Xr syslogd 8 ,
  so this option should only be used in debugging.
  .It Fl v
! Be verbose.
  In this mode it will print out each log and its
  reasons for either trimming that log or skipping it.
  .It Fl a Ar directory
--- 116,124 ----
  .Xr syslogd 8 ,
  so this option should only be used in debugging.
  .It Fl v
! Place
! .Nm newsyslog
! in verbose mode.
  In this mode it will print out each log and its
  reasons for either trimming that log or skipping it.
  .It Fl a Ar directory
***************
*** 180,191 ****
  The fields of the configuration file are as
  follows:
  .Bl -tag -width XXXXXXXXXXXXXXXX
! .It logfile name
  The full pathname of the system log file to be archived.
! .It owner.group of archives (optional)
! Specify an ownership and group for the archive file.
  The
! .Ql \&.
  is essential, even if the
  .Ar owner
  or
--- 182,193 ----
  The fields of the configuration file are as
  follows:
  .Bl -tag -width XXXXXXXXXXXXXXXX
! .It Ar logfile_name
  The full pathname of the system log file to be archived.
! .It Ar owner:group
! This optional field specifies the owner and group for the archive file.
  The
! .Ql :
  is essential, even if the
  .Ar owner
  or
***************
*** 193,207 ****
  field is left blank.
  The fields may be numeric, or a name which is looked up
  in the system password and group databases.
! .It mode of logfile & archives
! Octal mode of created log files and archives.
! .It number of archives
! Specify the number of archives to be kept besides the log file itself.
! .It size of archives
  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 a
! .Ql * ,
  then the size of
  the log file is not taken into account when determining when to trim the
  log file.
--- 195,213 ----
  field is left blank.
  The fields may be numeric, or a name which is looked up
  in the system password and group databases.
! For backwards compatibility, a
! .Ql \&.
! may be used instead of a
! .Ql : .
! .It Ar mode
! File mode (in octal) to use for created log files and archives.
! .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
  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.
***************
*** 212,225 ****
  .Nm
  from rotating files consisting solely of a message indicating
  that the log file has been turned over.
! .It archive interval
! Specify the time separation between the trimming of the log file.
! If this field is replaced by a
! .Ql * ,
! the number of hours since the last time the
! log was trimmed will not be taken into consideration.
! .It flags (optional)
  The
  .Ar flags
  field specifies if the archives should have any special processing
  done to the archived log files.
--- 218,355 ----
  .Nm
  from rotating files consisting solely of a message indicating
  that the log file has been turned over.
! .It Ar when
  The
+ .Ar when
+ field can consist of an interval, a specific time, or both.
+ If the
+ .Ar when
+ field consists of an asterisk
+ .Pq Ql \&* ,
+ log rotation will depend only on the contents of the
+ .Ar size
+ field.
+ Otherwise, the
+ .Ar when
+ field consists of an optional interval in hours, possibly followed
+ by an
+ .So Li \&@ Sc Ns No -sign
+ and a time in a restricted
+ .Tn ISO 8601
+ format or by a
+ .So Li \&$ Sc Ns No -sign
+ and a time specification for logfile rotation at a fixed time once
+ per day, per week or per month.
+ .Pp
+ If a time is specified, the log file will only be trimmed if
+ .Nm
+ is run within one hour of the specified time.
+ If an interval is specified, the log file will be trimmed if that
+ many hours have passed since the last rotation.
+ When both a time and an interval are specified, both conditions
+ must be satisfied for the rotation to take place.
+ .Pp
+ There is no provision for the specification of a timezone.
+ There is little point in specifying an explicit minutes or seconds
+ component in the current implementation, since the only comparison is
+ .Sq within the hour .
+ .Ss ISO 8601 restricted time format
+ The lead-in character for a restricted
+ .Tn ISO 8601
+ time is an
+ .So Li \&@ Sc Ns No -sign .
+ The particular format of the time in restricted
+ .Tn ISO 8601
+ is:
+ .Sm off
+ .Oo Oo Oo Oo Oo
+ .Va \&cc Oc
+ .Va \&yy Oc
+ .Va \&mm Oc
+ .Va \&dd Oc
+ .Oo Li \&T
+ .Oo Va \&hh
+ .Oo Va \&mm
+ .Oo Va \&ss
+ .Oc Oc Oc Oc Oc .
+ .Sm on
+ Optional date fields default to the appropriate component of the
+ current date; optional time fields default to midnight
+ For example, if today is January 22, 1999, the following date specifications
+ are all equivalent:
+ .Pp
+ .Bl -item -compact -offset indent
+ .It
+ .Ql 19990122T000000
+ .It
+ .Ql 990122T000000
+ .It
+ .Ql 0122T000000
+ .It
+ .Ql 22T000000
+ .It
+ .Ql T000000
+ .It
+ .Ql T0000
+ .It
+ .Ql T00
+ .It
+ .Ql 22T
+ .It
+ .Ql \&T
+ .It
+ .Ql \&
+ .El
+ .Ss Day, week and month time format
+ The lead-in character for day, week and month specification is a
+ .So Li \&$ Sc Ns No -sign .
+ The particular format of day, week and month specification is:
+ .Op Va D\&hh ,
+ .Op Va W\&w Ns Op Va D\&hh
+ and
+ .Op Va M\&dd Ns Op Va D\&hh ,
+ respectively.
+ Optional time fields default to midnight.
+ The ranges for day and hour specifications are:
+ .Pp
+ .Bl -tag -width Ds -compact -offset indent
+ .It Ar hh
+ hours, range 0 ... 23
+ .It Ar w
+ day of week, range 0 ... 6, 0 = Sunday
+ .It Ar dd
+ day of month, range 1 ... 31, or the letter
+ .Em L
+ or
+ .Em l
+ to specify the last day of the month.
+ .El
+ .Ss Some examples:
+ .Bl -tag -width Ds -compact -offset indent
+ .It Ar $D0
+ rotate every night at midnight
+ (same as
+ .Ar @T00 )
+ .It Ar $D23
+ rotate every day at 23:00 hr
+ (same as
+ .Ar @T23 )
+ .It Ar $W0D23
+ rotate every week on Sunday at 23:00 hr
+ .It Ar $W5D16
+ rotate every week on Friday at 16:00 hr
+ .It Ar $M1D0
+ rotate on the first day of every month at midnight
+ (i.e., the start of the day; same as
+ .Ar @01T00 )
+ .It Ar $M5D6
+ rotate on every 5th day of the month at 6:00 hr
+ (same as
+ .Ar @05T06 )
+ .El
+ .Pp
+ .It Ar flags
+ The optional
  .Ar flags
  field specifies if the archives should have any special processing
  done to the archived log files.
***************
*** 245,263 ****
  The
  .Sq F
  flag specifies that symbolic links should be followed.
! .It monitor notification (only used with the `M' flag)
  Specify the username (or email address) that should receive notification
  messages if this is a monitored log file.
  Notification messages are sent as email; the operator
  deserves what they get if they mark the
  .Xr sendmail 8
  log file as monitored.
! .It pid file (optional)
! Specify a file containing the PID of a process to send a
! .Dv SIGHUP
! signal to instead of
  .Pa /var/run/syslog.pid .
! .It signal (optional)
  Specify the signal to send to the process instead of
  .Dv SIGHUP .
  Signal names
--- 375,397 ----
  The
  .Sq F
  flag specifies that symbolic links should be followed.
! .It Ar monitor
  Specify the username (or email address) that should receive notification
  messages if this is a monitored log file.
  Notification messages are sent as email; the operator
  deserves what they get if they mark the
  .Xr sendmail 8
  log file as monitored.
! This field is only valid when the
! .Sq M
! flag is set.
! .It Ar pid_file
! This optional field specifies a file containing the PID of a process to send a
! signal (usually
! .Dv SIGHUP )
! to instead of
  .Pa /var/run/syslog.pid .
! .It Ar signal
  Specify the signal to send to the process instead of
  .Dv SIGHUP .
  Signal names
***************
*** 265,272 ****
  .Dq SIG
  and be the signal name, not the number, e.g.,
  .Dv SIGUSR1 .
! .It command (optional)
! Specify a command to run instead of sending a signal to the process.
  The command must be enclosed in double quotes
  .Pq Ql \&" .
  The empty string,
--- 399,407 ----
  .Dq SIG
  and be the signal name, not the number, e.g.,
  .Dv SIGUSR1 .
! .It Ar command
! This optional field specifies a command to run instead of sending a signal
! to the process.
  The command must be enclosed in double quotes
  .Pq Ql \&" .
  The empty string,