class FileChannel

Library: Foundation
Package: Logging
Header: Poco/FileChannel.h


A Channel that writes to a file. This class supports flexible log file rotation and archiving, as well as automatic purging of archived log files.

Only the message's text is written, followed by a newline.

Chain this channel to a FormattingChannel with an appropriate Formatter to control what is in the text.

The FileChannel 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).

The rotation strategy can be specified with the "rotation" property, which can take one of the follwing values:

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 "File System Tunneling Capabilities").

Using the "archive" property it is possible to specify how archived log files are named. The following values for the "archive" property are supported:

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:

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:

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.

The purgeAge property can have the following values:

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. When "none" or empty string are supplied, they reset purgeCount to none (no purging).

The flush property specifies whether each log message is flushed immediately to the log file (which may hurt application performance, but ensures that everything is in the log in case of a system crash), Valid values are:

For a more lightweight file channel class, see SimpleFileChannel.


Direct Base Classes: Channel

All Base Classes: Channel, Configurable, RefCountedObject

Member Summary

Member Functions: close, creationDate, getProperty, log, open, path, purge, setArchive, setCompress, setFlush, setProperty, setPurgeAge, setPurgeCount, setRotation, size

Inherited Functions: close, duplicate, getProperty, log, open, referenceCount, release, setProperty




Creates the FileChannel.


    const std::string & path

Creates the FileChannel for a file with the given path.


~FileChannel protected virtual


Member Functions

close virtual

void close();

Closes the FileChannel.

See also: Poco::Channel::close()


Timestamp creationDate() const;

Returns the log file's creation date.

getProperty virtual

std::string getProperty(
    const std::string & name
) const;

Returns the value of the property with the given name. See setProperty() for a description of the supported properties.

See also: Poco::Channel::getProperty()

log virtual

void log(
    const Message & msg

Logs the given message to the file.

See also: Poco::Channel::log()

open virtual

void open();

Opens the FileChannel and creates the log file if necessary.

See also: Poco::Channel::open()


const std::string & path() const;

Returns the log file's path.

setProperty virtual

void setProperty(
    const std::string & name,
    const std::string & value

Sets the property with the given name.

The following properties are supported:

See also: Poco::Channel::setProperty()


UInt64 size() const;

Returns the log file's current size in bytes.

purge protected

void purge();

setArchive protected

void setArchive(
    const std::string & archive

setCompress protected

void setCompress(
    const std::string & compress

setFlush protected

void setFlush(
    const std::string & flush

setPurgeAge protected

void setPurgeAge(
    const std::string & age

setPurgeCount protected

void setPurgeCount(
    const std::string & count

setRotation protected

void setRotation(
    const std::string & rotation



static const std::string PROP_ARCHIVE;


static const std::string PROP_COMPRESS;


static const std::string PROP_FLUSH;

PROP_PATH static

static const std::string PROP_PATH;


static const std::string PROP_PURGEAGE;


static const std::string PROP_PURGECOUNT;


static const std::string PROP_ROTATION;


static const std::string PROP_TIMES;