Class text_file_backend

boost::log::sinks::text_file_backend — An implementation of a text file logging sink backend.

Synopsis

// In header: <boost/log/sinks/text_file_backend.hpp>


class text_file_backend : public basic_formatted_sink_backend< char, combine_requirements< synchronized_feeding, flushing >::type >
{
public:
  // types
  typedef base_type::char_type            char_type;                      // Character type. 
  typedef base_type::string_type          string_type;                    // String type to be used as a message text holder. 
  typedef std::basic_ostream< char_type > stream_type;                    // Stream type. 
  typedef unspecified                     open_handler_type;              // File open handler. 
  typedef unspecified                     close_handler_type;             // File close handler. 
  typedef unspecified                     time_based_rotation_predicate;  // Predicate that defines the time-based condition for file rotation. 

  // construct/copy/destruct
  text_file_backend();
  template<typename... ArgsT> explicit text_file_backend(ArgsT... const &);
  ~text_file_backend();

  // public member functions
  template<typename PathT> void set_file_name_pattern(PathT const &);
  template<typename PathT> void set_target_file_name_pattern(PathT const &);
  void set_open_mode(std::ios_base::openmode);
  void set_file_collector(shared_ptr< file::collector > const &);
  void set_open_handler(open_handler_type const &);
  void set_close_handler(close_handler_type const &);
  void set_rotation_size(uintmax_t);
  void set_time_based_rotation(time_based_rotation_predicate const &);
  void enable_final_rotation(bool);
  void auto_flush(bool = true);
  void set_auto_newline_mode(auto_newline_mode);
  filesystem::path get_current_file_name() const;
  uintmax_t scan_for_files(file::scan_method = file::scan_matching, 
                           bool = true);
  void consume(record_view const &, string_type const &);
  void flush();
  void rotate_file();
};

Description

The sink backend puts formatted log records to a text file. The sink supports file rotation and advanced file control, such as size and file count restriction.

`text_file_backend` public construct/copy/destruct

```
text_file_backend();
```
Default constructor. The constructed sink backend uses default values of all the parameters.
```
template<typename... ArgsT> explicit text_file_backend(ArgsT... const & args);
```
Constructor. Creates a sink backend with the specified named parameters. The following named parameters are supported:
- file_name - Specifies the active file name pattern where logs are actually written to. The pattern may contain directory and file name portions, but only the file name may contain placeholders. The backend supports Boost.DateTime placeholders for injecting current time and date into the file name. Also, an additional N placeholder is supported, it will be replaced with an integral increasing file counter. The placeholder may also contain width specification in the printf-compatible form (e.g. %5N). The printed file counter will always be zero-filled. If file_name is not specified, pattern "%5N.log" will be used.
- target_file_name - Specifies the target file name pattern to use to rename the log file on rotation, before passing it to the file collector. The pattern may contain the same placeholders as the file_name parameter. By default, no renaming is done, i.e. the written log file keeps its name according to file_name.
- open_mode - File open mode. The mode should be presented in form of mask compatible to std::ios_base::openmode. If not specified, trunc | out will be used.
- rotation_size - Specifies the approximate size, in characters written, of the temporary file upon which the file is passed to the file collector. Note the size does not count any possible character conversions that may take place during writing to the file. If not specified, the file won't be rotated upon reaching any size.
- time_based_rotation - Specifies the predicate for time-based file rotation. No time-based file rotations will be performed, if not specified.
- enable_final_rotation - Specifies a flag, whether or not perform log file rotation on sink backend destruction. By default, is true.
- auto_flush - Specifies a flag, whether or not to automatically flush the file after each written log record. By default, is false.
- auto_newline_mode - Specifies automatic trailing newline insertion mode. Must be a value of the auto_newline_mode enum. By default, is auto_newline_mode::insert_if_missing.
Note

Read the caution note regarding file name pattern in the sinks::file::collector::scan_for_files documentation.
```
~text_file_backend();
```
Destructor

`text_file_backend` public member functions

```
template<typename PathT> void set_file_name_pattern(PathT const & pattern);
```
The method sets the active file name wildcard for the files being written. The wildcard supports date and time injection into the file name.

Parameters:

pattern

The name pattern for the file being written.
```
template<typename PathT> 
  void set_target_file_name_pattern(PathT const & pattern);
```
The method sets the target file name wildcard for the files being rotated. The wildcard supports date and time injection into the file name.

This pattern will be used when the log file is being rotated, to rename the just written log file (which has the name according to the pattern in the file_name constructor parameter or set by a call to set_file_name_pattern), just before passing the file to the file collector.

Parameters:

pattern

The name pattern for the file being rotated.
```
void set_open_mode(std::ios_base::openmode mode);
```
The method sets the file open mode

Parameters:

mode

File open mode
```
void set_file_collector(shared_ptr< file::collector > const & collector);
```
The method sets the log file collector function. The function is called on file rotation and is being passed the written file name.

Parameters:

collector

The file collector function object
```
void set_open_handler(open_handler_type const & handler);
```
The method sets file opening handler. The handler will be called every time the backend opens a new temporary file. The handler may write a header to the opened file in order to maintain file validity.

Parameters:

handler

The file open handler function object
```
void set_close_handler(close_handler_type const & handler);
```
The method sets file closing handler. The handler will be called every time the backend closes a temporary file. The handler may write a footer to the opened file in order to maintain file validity.

Parameters:

handler

The file close handler function object
```
void set_rotation_size(uintmax_t size);
```
The method sets maximum file size. When the size is reached, file rotation is performed.

Note

The size does not count any possible character translations that may happen in the underlying API. This may result in greater actual sizes of the written files.

Parameters:

size

The maximum file size, in characters.
```
void set_time_based_rotation(time_based_rotation_predicate const & predicate);
```
The method sets the predicate that defines the time-based condition for file rotation.

Note

The rotation always occurs on writing a log record, so the rotation is not strictly bound to the specified condition.

Parameters:

predicate

The predicate that defines the time-based condition for file rotation. If empty, no time-based rotation will take place.
```
void enable_final_rotation(bool enable);
```
The method allows to enable or disable log file rotation on sink destruction.

By default the sink backend will rotate the log file, if it's been written to, on destruction.

Parameters:

enable

The flag indicates whether the final rotation should be performed.
```
void auto_flush(bool enable = true);
```
Sets the flag to automatically flush write buffers of the file being written after each log record.

Parameters:

enable

The flag indicates whether the automatic buffer flush should be performed.
```
void set_auto_newline_mode(auto_newline_mode mode);
```
Selects whether a trailing newline should be automatically inserted after every log record. See auto_newline_mode description for the possible modes of operation.

Parameters:

mode

The trailing newline insertion mode.
```
filesystem::path get_current_file_name() const;
```
Returns:

The name of the currently open log file. If no file is open, returns an empty path.

uintmax_t scan_for_files(file::scan_method method = file::scan_matching, 
                         bool update_counter = true);

Performs scanning of the target directory for log files that may have been left from previous runs of the application. The found files are considered by the file collector as if they were rotated.

The file scan can be performed in two ways: either all files in the target directory will be considered as log files, or only those files that satisfy the target file name pattern. See documentation on sinks::file::collector::scan_for_files for more information.

	Note
	The method essentially delegates to the same-named function of the file collector.

Parameters:

`method`	File scanning method
`update_counter`	If `true` and method is `scan_matching`, the method attempts to update the internal file counter according to the found files. The counter is unaffected otherwise.

Requires:

File collector and the proper file name pattern have already been set.

Returns:

The number of files found.

void consume(record_view const & rec, string_type const & formatted_message);

The method writes the message to the sink

```
void flush();
```
The method flushes the currently open log file
```
void rotate_file();
```
The method rotates the file

	Note
	Read the caution note regarding file name pattern in the `sinks::file::collector::scan_for_files` documentation.

	Note
	The size does not count any possible character translations that may happen in the underlying API. This may result in greater actual sizes of the written files.

	Note
	The rotation always occurs on writing a log record, so the rotation is not strictly bound to the specified condition.

Boost C++ Libraries