1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Class Poco::FileChannel</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta name="author" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="publisher" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="copyright" content="Copyright (c) 2009, Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="language" content="en"/>
<meta name="date" content="2009-11-24"/>
<meta name="generator" content="PocoDoc"/>
<link rel="stylesheet" href="css/styles.css" type="text/css"/>
</head>
<body bgcolor="#ffffff" leftmargin="0" topmargin="0">
<div class="header">
<h1 class="namespace"><a href="Poco.html" class="namespace">Poco</a></h1>
<h1 class="symbol">class FileChannel</h1>
</div>
<div class="body">
<p>
<b>Library:</b> Foundation<br />
<b>Package:</b> Logging<br />
<b>Header:</b> Poco/FileChannel.h</p>
<h2>Description</h2>
<div class="description">
<p>A <a href="Poco.Channel.html" title="class Poco::Channel">Channel</a> that writes to a file. This class supports flexible log file rotation and archiving, as well as automatic purging of archived log files. </p>
<p>Only the message's text is written, followed by a newline. </p>
<p>Chain this channel to a <a href="Poco.FormattingChannel.html" title="class Poco::FormattingChannel">FormattingChannel</a> with an appropriate <a href="Poco.Formatter.html" title="class Poco::Formatter">Formatter</a> to control what is in the text. </p>
<p>The <a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a> support log file rotation based on log file size or time intervals. Archived log files can be compressed in gzip format. Older archived files can be automatically deleted (purged). </p>
<p>The rotation strategy can be specified with the "rotation" property, which can take one of the follwing values: </p>
<p></p>
<ul>
<li>never: no log rotation </li>
<li>[day,][hh]:mm: the file is rotated on specified day/time day - day is specified as long or short day name (Monday|Mon, Tuesday|Tue, ... ); day can be omitted, in which case log is rotated every day hh - valid hour range is 00-23; hour can be omitted, in which case log is rotated every hour mm - valid minute range is 00-59; minute must be specified </li>
<li>daily: the file is rotated daily </li>
<li>weekly: the file is rotated every seven days </li>
<li>monthly: the file is rotated every 30 days </li>
<li><n> minutes: the file is rotated every <n> minutes, where <n> is an integer greater than zero. </li>
<li><n> hours: the file is rotated every <n> hours, where <n> is an integer greater than zero. </li>
<li><n> days: the file is rotated every <n> days, where <n> is an integer greater than zero. </li>
<li><n> weeks: the file is rotated every <n> weeks, where <n> is an integer greater than zero. </li>
<li><n> months: the file is rotated every <n> months, where <n> is an integer greater than zero and a month has 30 days. </li>
<li><n>: the file is rotated when its size exceeds <n> bytes. </li>
<li><n> K: the file is rotated when its size exceeds <n> Kilobytes. </li>
<li><n> M: the file is rotated when its size exceeds <n> Megabytes. </li>
</ul>
<p>NOTE: For periodic log file rotation (daily, weekly, monthly, etc.), the date and time of log file creation or last rotation is written into the first line of the log file. This is because there is no reliable way to find out the real creation date of a file on many platforms (e.g., most Unix platforms do not provide the creation date, and Windows has its own issues with its "<a href="Poco.File.html" title="class Poco::File">File</a> System Tunneling Capabilities"). </p>
<p>Using the "archive" property it is possible to specify how archived log files are named. The following values for the "archive" property are supported: </p>
<p></p>
<ul>
<li>number: A number, starting with 0, is appended to the name of archived log files. The newest archived log file always has the number 0. For example, if the log file is named "access.log", and it fulfils the criteria for rotation, the file is renamed to "access.log.0". If a file named "access.log.0" already exists, it is renamed to "access.log.1", and so on. </li>
<li>timestamp: A timestamp is appended to the log file name. For example, if the log file is named "access.log", and it fulfils the criteria for rotation, the file is renamed to "access.log.20050802110300". </li>
</ul>
<p>Using the "times" property it is possible to specify time mode for the day/time based rotation. The following values for the "times" property are supported: </p>
<p></p>
<ul>
<li>utc: Rotation strategy is based on UTC time (default). </li>
<li>local: Rotation strategy is based on local time. </li>
</ul>
<p>Archived log files can be compressed using the gzip compression method. Compressing can be controlled with the "compression" property. The following values for the "compress" property are supported: </p>
<p></p>
<ul>
<li>true: Compress archived log files. </li>
<li>false: Do not compress archived log files. </li>
</ul>
<p>Archived log files can be automatically purged, either if they reach a certain age, or if the number of archived log files reaches a given maximum number. This is controlled by the purgeAge and purgeCount properties. </p>
<p>The purgeAge property can have the following values: </p>
<p></p>
<ul>
<li><n> [seconds] the maximum age is <n> seconds. </li>
<li><n> minutes: the maximum age is <n> minutes. </li>
<li><n> hours: the maximum age is <n> hours. </li>
<li><n> days: the maximum age is <n> days. </li>
<li><n> weeks: the maximum age is <n> weeks. </li>
<li><n> months: the maximum age is <n> months, where a month has 30 days. </li>
</ul>
<p>The purgeCount property has an integer value that specifies the maximum number of archived log files. If the number is exceeded, archived log files are deleted, starting with the oldest. </p>
<p>For a more lightweight file channel class, see <a href="Poco.SimpleFileChannel.html" title="class Poco::SimpleFileChannel">SimpleFileChannel</a>. </p>
</div>
<h2>Inheritance</h2>
<p><b>Direct Base Classes: </b><a href="Poco.Channel.html" title="class Poco::Channel">Channel</a></p>
<p><b>All Base Classes: </b><a href="Poco.Channel.html" title="class Poco::Channel">Channel</a>, <a href="Poco.Configurable.html" title="class Poco::Configurable">Configurable</a>, <a href="Poco.RefCountedObject.html" title="class Poco::RefCountedObject">RefCountedObject</a></p>
<h2>Member Summary</h2>
<p><b>Member Functions: </b><a href="Poco.FileChannel.html#6988" title="Poco::FileChannel::close()">close</a>, <a href="Poco.FileChannel.html#6996" title="Poco::FileChannel::creationDate()">creationDate</a>, <a href="Poco.FileChannel.html#6994" title="Poco::FileChannel::getProperty()">getProperty</a>, <a href="Poco.FileChannel.html#6989" title="Poco::FileChannel::log()">log</a>, <a href="Poco.FileChannel.html#6987" title="Poco::FileChannel::open()">open</a>, <a href="Poco.FileChannel.html#6998" title="Poco::FileChannel::path()">path</a>, <a href="Poco.FileChannel.html#7017" title="Poco::FileChannel::purge()">purge</a>, <a href="Poco.FileChannel.html#7009" title="Poco::FileChannel::setArchive()">setArchive</a>, <a href="Poco.FileChannel.html#7011" title="Poco::FileChannel::setCompress()">setCompress</a>, <a href="Poco.FileChannel.html#6991" title="Poco::FileChannel::setProperty()">setProperty</a>, <a href="Poco.FileChannel.html#7013" title="Poco::FileChannel::setPurgeAge()">setPurgeAge</a>, <a href="Poco.FileChannel.html#7015" title="Poco::FileChannel::setPurgeCount()">setPurgeCount</a>, <a href="Poco.FileChannel.html#7007" title="Poco::FileChannel::setRotation()">setRotation</a>, <a href="Poco.FileChannel.html#6997" title="Poco::FileChannel::size()">size</a></p>
<p><b>Inherited Functions: </b><a href="Poco.Channel.html#4145" title="Poco::Channel::close()">close</a>, <a href="Poco.RefCountedObject.html#9659" title="Poco::RefCountedObject::duplicate()">duplicate</a>, <a href="Poco.Channel.html#4151" title="Poco::Channel::getProperty()">getProperty</a>, <a href="Poco.Channel.html#4146" title="Poco::Channel::log()">log</a>, <a href="Poco.Channel.html#4144" title="Poco::Channel::open()">open</a>, <a href="Poco.RefCountedObject.html#9661" title="Poco::RefCountedObject::referenceCount()">referenceCount</a>, <a href="Poco.RefCountedObject.html#9660" title="Poco::RefCountedObject::release()">release</a>, <a href="Poco.Channel.html#4148" title="Poco::Channel::setProperty()">setProperty</a></p>
<h2>Constructors</h2>
<h3><a name="6984">FileChannel</a></h3>
<p class="decl"><a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a>();</p>
<div class="description">
<p>Creates the <a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a>. </p>
</div>
<h3><a name="6985">FileChannel</a></h3>
<p class="decl"><a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a>(<br /> const std::string & path<br />);</p>
<div class="description">
<p>Creates the <a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a> for a file with the given path. </p>
</div>
<h2>Destructor</h2>
<h3><a name="7006">~FileChannel</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">~<a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a>();</p>
<div class="description">
<p></p>
</div>
<h2>Member Functions</h2>
<h3><a name="6988">close</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void close();</p>
<div class="description">
<p>Closes the <a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a>. </p>
</div>
<div class="description"><p><b>See also:</b> <a href="Poco.Channel.html#4145" title="Poco::Channel::close()">Poco::Channel::close()</a></p></div>
<h3><a name="6996">creationDate</a></h3>
<p class="decl"><a href="Poco.Timestamp.html" title="class Poco::Timestamp">Timestamp</a> creationDate() const;</p>
<div class="description">
<p>Returns the log file's creation date. </p>
</div>
<h3><a name="6994">getProperty</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">std::string getProperty(<br /> const std::string & name<br />) const;</p>
<div class="description">
<p>Returns the value of the property with the given name. See <a href="Poco.FileChannel.html#6991" title="Poco::FileChannel::setProperty()">setProperty</a>() for a description of the supported properties. </p>
</div>
<div class="description"><p><b>See also:</b> <a href="Poco.Channel.html#4151" title="Poco::Channel::getProperty()">Poco::Channel::getProperty()</a></p></div>
<h3><a name="6989">log</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void log(<br /> const <a href="Poco.Message.html" title="class Poco::Message">Message</a> & msg<br />);</p>
<div class="description">
<p>Logs the given message to the file. </p>
</div>
<div class="description"><p><b>See also:</b> <a href="Poco.Channel.html#4146" title="Poco::Channel::log()">Poco::Channel::log()</a></p></div>
<h3><a name="6987">open</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void open();</p>
<div class="description">
<p>Opens the <a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a> and creates the log file if necessary. </p>
</div>
<div class="description"><p><b>See also:</b> <a href="Poco.Channel.html#4144" title="Poco::Channel::open()">Poco::Channel::open()</a></p></div>
<h3><a name="6998">path</a></h3>
<p class="decl">const std::string & path() const;</p>
<div class="description">
<p>Returns the log file's path. </p>
</div>
<h3><a name="6991">setProperty</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void setProperty(<br /> const std::string & name,<br /> const std::string & value<br />);</p>
<div class="description">
<p>Sets the property with the given name. </p>
<p>The following properties are supported: </p>
<ul>
<li>path: The log file's path. </li>
<li>rotation: The log file's rotation mode. See the <a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a> class for details. </li>
<li>archive: The log file's archive mode. See the <a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a> class for details. </li>
<li>times: The log file's time mode. See the <a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a> class for details. </li>
<li>compress: Enable or disable compression of archived files. See the <a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a> class for details. </li>
<li>purgeAge: Maximum age of an archived log file before it is purged. See the <a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a> class for details. </li>
<li>purgeCount: Maximum number of archived log files before files are purged. See the <a href="Poco.FileChannel.html" title="class Poco::FileChannel">FileChannel</a> class for details. </li>
</ul>
</div>
<div class="description"><p><b>See also:</b> <a href="Poco.Channel.html#4148" title="Poco::Channel::setProperty()">Poco::Channel::setProperty()</a></p></div>
<h3><a name="6997">size</a></h3>
<p class="decl"><a href="Poco.html#11358" title="Poco::UInt64">UInt64</a> size() const;</p>
<div class="description">
<p>Returns the log file's current size in bytes. </p>
</div>
<h3><a name="7017">purge</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void purge();</p>
<div class="description">
<p></p>
</div>
<h3><a name="7009">setArchive</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void setArchive(<br /> const std::string & archive<br />);</p>
<div class="description">
<p></p>
</div>
<h3><a name="7011">setCompress</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void setCompress(<br /> const std::string & compress<br />);</p>
<div class="description">
<p></p>
</div>
<h3><a name="7013">setPurgeAge</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void setPurgeAge(<br /> const std::string & age<br />);</p>
<div class="description">
<p></p>
</div>
<h3><a name="7015">setPurgeCount</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void setPurgeCount(<br /> const std::string & count<br />);</p>
<div class="description">
<p></p>
</div>
<h3><a name="7007">setRotation</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void setRotation(<br /> const std::string & rotation<br />);</p>
<div class="description">
<p></p>
</div>
<h2>Variables</h2>
<h3><a name="7001">PROP_ARCHIVE</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static const std::string <a href="Poco.FileChannel.html#7001" title="Poco::FileChannel::PROP_ARCHIVE">PROP_ARCHIVE</a>;</p>
<div class="description">
<p></p>
</div>
<h3><a name="7003">PROP_COMPRESS</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static const std::string <a href="Poco.FileChannel.html#7003" title="Poco::FileChannel::PROP_COMPRESS">PROP_COMPRESS</a>;</p>
<div class="description">
<p></p>
</div>
<h3><a name="6999">PROP_PATH</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static const std::string <a href="Poco.FileChannel.html#6999" title="Poco::FileChannel::PROP_PATH">PROP_PATH</a>;</p>
<div class="description">
<p></p>
</div>
<h3><a name="7004">PROP_PURGEAGE</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static const std::string <a href="Poco.FileChannel.html#7004" title="Poco::FileChannel::PROP_PURGEAGE">PROP_PURGEAGE</a>;</p>
<div class="description">
<p></p>
</div>
<h3><a name="7005">PROP_PURGECOUNT</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static const std::string <a href="Poco.FileChannel.html#7005" title="Poco::FileChannel::PROP_PURGECOUNT">PROP_PURGECOUNT</a>;</p>
<div class="description">
<p></p>
</div>
<h3><a name="7000">PROP_ROTATION</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static const std::string <a href="Poco.FileChannel.html#7000" title="Poco::FileChannel::PROP_ROTATION">PROP_ROTATION</a>;</p>
<div class="description">
<p></p>
</div>
<h3><a name="7002">PROP_TIMES</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static const std::string <a href="Poco.FileChannel.html#7002" title="Poco::FileChannel::PROP_TIMES">PROP_TIMES</a>;</p>
<div class="description">
<p></p>
</div>
<p class="footer">POCO C++ Libraries 1.3.6-all<br />
Copyright © 2009, <a href="http://pocoproject.org/" target="_blank">Applied Informatics Software Engineering GmbH and Contributors</a></p>
</div>
</body>
</html>
|
