From 4f802ac2b6dfbf28de270dafcf11f8d71a607b81 Mon Sep 17 00:00:00 2001
From: Johannes Gijsbers <jlg@dds.nl>
Date: Sun, 7 Nov 2004 14:14:27 +0000
Subject: [PATCH] Patch #1061857: add documentation for previously undocumented
 TimedRotatingFileHandler class. Thanks Jeroen Vloothuis!

---
 Doc/lib/liblogging.tex | 49 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/Doc/lib/liblogging.tex b/Doc/lib/liblogging.tex
index a4660a53e8d..4725d58e32a 100644
--- a/Doc/lib/liblogging.tex
+++ b/Doc/lib/liblogging.tex
@@ -80,6 +80,9 @@ files.
 \item \class{RotatingFileHandler} instances send error messages to disk
 files, with support for maximum log file sizes and log file rotation.
 
+\item \class{TimedRotatingFileHandler} instances send error messages to
+disk files rotating the log file at certain timed intervals.
+
 \item \class{SocketHandler} instances send error messages to
 TCP/IP sockets.
 
@@ -891,6 +894,52 @@ Outputs the record to the file, catering for rollover as described
 in \method{setRollover()}.
 \end{methoddesc}
 
+\subsubsection{TimedRotatingFileHandler}
+
+The \class{TimedRotatingFileHandler} class supports rotation of disk log files
+at certain timed intervals.
+
+\begin{classdesc}{TimedRotatingFileHandler}{filename
+                                            \optional{,when
+                                            \optional{,interval
+                                            \optional{,backupCount}}}}
+
+Returns a new instance of the \class{TimedRotatingFileHandler} class. The
+specified file is opened and used as the stream for logging. On rotating
+it also sets the filename suffix. Rotating happens based on the product
+of \var{when} and \var{interval}. 
+
+You can use the \var{when} to specify the type of \var{interval}. The
+list of possible values is, note that they are not case sensitive:
+
+\begin{tableii}{l|l}{}{Value}{Type of interval}
+  \lineii{S}{Seconds}
+  \lineii{M}{Minutes}
+  \lineii{H}{Hours}
+  \lineii{D}{Days}
+  \lineii{W}{Week day (0=Monday)}
+  \lineii{midnight}{Roll over at midnight}
+\end{tableii}
+
+If \var{backupCount} is non-zero, the system will save old log files by
+appending the extensions ".1", ".2" etc., to the filename. For example,
+with a \var{backupCount} of 5 and a base file name of \file{app.log},
+you would get \file{app.log}, \file{app.log.1}, \file{app.log.2}, up to
+\file{app.log.5}. The file being written to is always \file{app.log}.
+When this file is filled, it is closed and renamed to \file{app.log.1},
+and if files \file{app.log.1}, \file{app.log.2}, etc. exist, then they
+are renamed to \file{app.log.2}, \file{app.log.3} etc. respectively.
+\end{classdesc}
+
+\begin{methoddesc}{doRollover}{}
+Does a rollover, as described above.
+\end{methoddesc}
+
+\begin{methoddesc}{emit}{record}
+Outputs the record to the file, catering for rollover as described
+above.
+\end{methoddesc}
+
 \subsubsection{SocketHandler}
 
 The \class{SocketHandler} class sends logging output to a network