<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class LogChannelFiles - Class LogChannelFiles</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./modules.html"><span>Modules</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./enum.html"><span>Enumerations</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class LogChannelFiles<span class="faldoc_belong"><a href="./module_feather_logging.html">[in Logging support]</a></p></h1>
<p class="faldoc_brief">Log channel sending logs to a set of (possibly) rotating local files. </p>
<p class="faldoc_funcdecl">
<b>class</b> LogChannelFiles( path, [level], [format], [maxCount], [maxSize], [maxDays], [overwrite], [flushAll] )
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#flushAll">flushAll</a></td><td>When true, all the log operations cause an immediate flush of the underlying stream. </td></tr>
<tr><td><a href="#maxCount">maxCount</a></td><td>Maximum number of rolled back log files before starting deleting them. </td></tr>
<tr><td><a href="#maxDays">maxDays</a></td><td>Number of days to keep logging on the master file before rolling it. </td></tr>
<tr><td><a href="#maxSize">maxSize</a></td><td>Maximum size of the main log file before being automatically rolled. </td></tr>
<tr><td><a href="#overwrite">overwrite</a></td><td>If true, opening a non-empty log will delete it. </td></tr>
<tr><td><a href="#path">path</a></td><td>Contains the path to the master log file. </td></tr>
<tr><td><a href="#open">open()</a></td><td>Opens the stream to the given main log file. </td></tr>
<tr><td><a href="#reset">reset()</a></td><td>Clears the current log file. </td></tr>
<tr><td><a href="#rotate">rotate()</a></td><td>Rotates the current log file. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> LogChannelFiles( path, [level], [format], [maxCount], [maxSize], [maxDays], [overwrite], [flushAll] )
</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">The complete filename were the logs are to be sent. </td></tr>
<tr><td class="faldoc_optparam">level</td><td class="faldoc_optparamdesc">Minimum severity level logged by this channel. </td></tr><tr><td class="faldoc_optparam">format</td><td class="faldoc_optparamdesc">Message formatting used by this channel. </td></tr><tr><td class="faldoc_optparam">maxCount</td><td class="faldoc_optparamdesc">Number of maximum log files generated by this channel. </td></tr><tr><td class="faldoc_optparam">maxSize</td><td class="faldoc_optparamdesc">Maximum size of each file. </td></tr><tr><td class="faldoc_optparam">maxDays</td><td class="faldoc_optparamdesc">Maximum days of lifetime for each file. </td></tr><tr><td class="faldoc_optparam">overwrite</td><td class="faldoc_optparamdesc">If true, overwrite the base log file on open, if found. </td></tr><tr><td class="faldoc_optparam">flushAll</td><td class="faldoc_optparamdesc">If false, do NOT flush at every log entry. </td></tr>
</table>
<br/>
<p class="item_brief">Log channel sending logs to a set of (possibly) rotating local files. </p>
<p class="faldoc_text">This log channel is meant to write to one local file, and to possibly swap it into spare files when some criterion are met. </p>
<p class="faldoc_text">In its basic default configuration, this stream channel works as a LogChannelStream provided with a stream open on a local file via InputOutput stream (appending at bottom, or eventually creating the file). </p>
<p class="faldoc_text"> If the <b>maxSize</b> parameter is given, the file is rotated (closed and renamed) when it grows beyond the given dimension (in bytes). </p>
<p class="faldoc_text"> If the <b>maxDays</b> parameter is given, the file is rotated after a maximum number of days since its creation. </p>
<p class="faldoc_text"> If both <b>maxSize</b> and <b>maxDays</b> parameters are given, the file is rotated when the first boundary is met. </p>
<p class="faldoc_text"> The action performed when rotating a file is determined by the <b>maxCount</b> parameter. If it's zero (the default), the log file is simply truncated to 0, that is to say, the writing starts anew. Any other value indicates the maximum number of back-rotated files created by this channel. Files are rotated by adding a numeric suffix to them; the currently active log file is unnumbered, the most recent log file is renumbered as 1, the second last most recent is numbered 2 up to the value of <b>maxCount</b> parameter. When all the positions are occupied and a new rotation takes place, the oldest file is deleted. </p>
<p class="faldoc_text"> The rotated file names are composed of the <b>path</b> parameter and a zero padded number wide enough to accommodate all the numbers up to <b>maxCount;</b> the number is generally appended to the <b>path</b> through a "." separator, but it is possible to override this by passing a path containing a "%" (percent) character, which gets substituted by the padded number. In this case, the main file is numbered 0. </p>
<p class="faldoc_text"> For example, files generated through the path "logs/my_app.%.log" with a <b>maxCount</b> of 10 will be numbered as (oldest to newest): </p>
<pre class="faldoc_code">
logs/my_app.10.log
logs/my_app.09.log
logs/my_app.08.log
...
logs/my_app.01.log
logs/my_app.00.log
</pre>
<p class="faldoc_text">while files created through the path "logs/my_app.log" would be numbered: </p>
<pre class="faldoc_code">
logs/my_app.log.10
logs/my_app.log.09
logs/my_app.log.08
...
logs/my_app.log.01
logs/my_app.log
</pre>
<p class="faldoc_text"> If the <b>overwrite</b> parameter is true, then the the main file will be overwritten in case it exists when opening the log. </p>
<p class="faldoc_text"> Finally, if the <b>flushAll</b> parameter is false, then the stream buffer won't be flushed after each log operation. </p>
<p class="faldoc_text"> This log channel doesn't try to create immediately the main file; this is done the first time a log request is processed, or explicitly through the <a href="./class_LogChannelFiles.html#open">LogChannelFiles.open</a> method. In the first case, a log request advanced by a log area may raise an IoError when </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> All the parameters can be hot-changed in any moment, except for the <b>path</b> parameter that is read-only. </p>
<h2 class="faldoc_title">Properties</h2>
<h3 class="faldoc_funcname"><a name="flushAll">flushAll</a></h3>
<p class="item_brief">When true, all the log operations cause an immediate flush of the underlying stream. </p>
<h3 class="faldoc_funcname"><a name="maxCount">maxCount</a></h3>
<p class="item_brief">Maximum number of rolled back log files before starting deleting them. </p>
<p class="faldoc_text"><p class="faldoc_text">Zero means that the file is never rolled back; eventually, when hitting a limit, it is truncated from the beginning and the log starts all over. </p>
</p>
<h3 class="faldoc_funcname"><a name="maxDays">maxDays</a></h3>
<p class="item_brief">Number of days to keep logging on the master file before rolling it. </p>
<p class="faldoc_text"><p class="faldoc_text">Zero means disabled. </p>
</p>
<h3 class="faldoc_funcname"><a name="maxSize">maxSize</a></h3>
<p class="item_brief">Maximum size of the main log file before being automatically rolled. </p>
<p class="faldoc_text"><p class="faldoc_text">Zero means disabled; that is, the size of the log file is unlimited. </p>
</p>
<h3 class="faldoc_funcname"><a name="overwrite">overwrite</a></h3>
<p class="item_brief">If true, opening a non-empty log will delete it. </p>
<p class="faldoc_text"><p class="faldoc_text">The default for this property is false. This means that the default behavior is that to append log entries to the previously existing ones. </p>
</p>
<h3 class="faldoc_funcname"><a name="path">path</a></h3>
<p class="item_brief">Contains the path to the master log file. </p>
<p class="faldoc_text"><p class="faldoc_text">This property is read-only. </p>
</p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="open">open()</a></h3>
<p class="item_brief">Opens the stream to the given main log file. </p>
<p class="faldoc_funcdecl">LogChannelFiles.open( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>IoError</i></b></td><td class="faldoc_raisedesc">if the file can't be opened. </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="reset">reset()</a></h3>
<p class="item_brief">Clears the current log file. </p>
<p class="faldoc_funcdecl">LogChannelFiles.reset( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>IoError</i></b></td><td class="faldoc_raisedesc">if the truncate operation files. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This operation clears the log file without rotating it. Some applications, in certain moments, know that the previous log is useless and to be discarded, for example because they want to debug the operations from that point on. </p>
<p class="faldoc_text">This method also forces do discard all the pending messages that was queued for logging but still unwritten. </p>
</p>
<h3 class="faldoc_funcname"><a name="rotate">rotate()</a></h3>
<p class="item_brief">Rotates the current log file. </p>
<p class="faldoc_funcdecl">LogChannelFiles.rotate( )</p>
<p class="faldoc_text"><p class="faldoc_text"> This operation perform a rotation operation, respecting the default behavior specified through the <a href="./class_LogChannelFiles.html#maxCount">LogChannelFiles.maxCount</a> property, as if one of the limits were hit. </p>
<p class="faldoc_text">The operation is actually queued after all pending messages; new messages posted after this operation will go to the new main file after the rotation, while the pending messages will be written to the new log stream. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> A failure in the rotate operation will cause the operation to silently fail and the log to keep being sent to the current log file. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./modules.html">Modules</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./enum.html">Enumerations</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
