Boost C++ Libraries

#include <boost/log/utility/manipulators/to_log.hpp>

The to_log function creates a stream manipulator that simply outputs the adopted value to the stream. By default its behavior is equivalent to simply putting the value to the stream. However, the user is able to overload the operator<< for the adopted value to override formatting behavior when values are formatted for logging purposes. This is typically desired when the regular operator<< is employed for other tasks (such as serialization) and its behavior is neither suitable for logging nor can be easily changed. For example:

std::ostream& operator<<
(
    std::ostream& strm,
    logging::to_log_manip< int > const& manip
)
{
    strm << std::setw(4) << std::setfill('0') << std::hex << manip.get() << std::dec;
    return strm;
}

void test_manip()
{
    std::cout << "Regular output: " << 1010 << std::endl;
    std::cout << "Log output: " << logging::to_log(1010) << std::endl;
}

The second streaming statement in the test_manip function will invoke our custom stream insertion operator which defines special formatting rules.

It is also possible to define different formatting rules for different value contexts as well. The library uses this feature to allow different formatting ruled for different attribute values, even if the stored value type is the same. To do so one has to specify an explicit template argument for to_log, a tag type, which will be embedded into the manipulator type and thus will allow to define different insertion operators:

struct tag_A;
struct tag_B;

std::ostream& operator<<
(
    std::ostream& strm,
    logging::to_log_manip< int, tag_A > const& manip
)
{
    strm << "A[" << manip.get() << "]";
    return strm;
}

std::ostream& operator<<
(
    std::ostream& strm,
    logging::to_log_manip< int, tag_B > const& manip
)
{
    strm << "B[" << manip.get() << "]";
    return strm;
}

void test_manip_with_tag()
{
    std::cout << "Regular output: " << 1010 << std::endl;
    std::cout << "Log output A: " << logging::to_log< tag_A >(1010) << std::endl;
    std::cout << "Log output B: " << logging::to_log< tag_B >(1010) << std::endl;
}

See the complete code.

	Note
	The library uses basic_formatting_ostream stream type for record formatting, so when customizing attribute value formatting rules the operator<< must use basic_formatting_ostream instead of std::ostream.

#include <boost/log/utility/manipulators/add_value.hpp>

The add_value function creates a manipulator that attaches an attribute value to a log record. This manipulator can only be used in streaming expressions with the basic_record_ostream stream type (which is the case when log record message is formatted). Since the message text is only formatted after filtering, attribute values attached with this manipulator do not affect filtering and can only be used in formatters and sinks themselves.

In addition to the value itself, the manipulator also requires the attribute name to be provided. For example:

// Creates a log record with attribute value "MyAttr" of type int attached
BOOST_LOG(lg) << logging::add_value("MyAttr", 10) << "Hello world!";

#include <boost/log/utility/manipulators/dump.hpp>

The dump function creates a manipulator that outputs binary contents of a contiguous memory region. This can be useful for logging some low level binary data, such as encoded network packets or entries of a binary file. The use is quite straightforward:

void on_receive(std::vector< unsigned char > const& packet)
{
    // Outputs something like "Packet received: 00 01 02 0a 0b 0c"
    BOOST_LOG(lg) << "Packet received: " << logging::dump(packet.data(), packet.size());
}

The manipulator also allows to limit the amount of data to be output, in case if the input data can be too large. Just specify the maximum number of bytes of input to dump as the last argument:

void on_receive(std::vector< unsigned char > const& packet)
{
    // Outputs something like "Packet received: 00 01 02 03 04 05 06 07 and 67 bytes more"
    BOOST_LOG(lg) << "Packet received: " << logging::dump(packet.data(), packet.size(), 8);
}

There is another manipulator called dump_elements for printing binary representation of non-byte array elements. The special manipulator for this case is necessary because the units of the size argument of dump can be confusing (is it in bytes or in elements?). Therefore dump will not compile when used for non-byte input data. dump_elements accepts the same arguments, and its size-related arguments always designate the number of elements to process.

void process(std::vector< double > const& matrix)
{
    // Note that dump_elements accepts the number of elements in the matrix, not its size in bytes
    BOOST_LOG(lg) << "Matrix dump: " << logging::dump_elements(matrix.data(), matrix.size());
}

	Tip
	Both these manipulators can also be used with regular output streams, not necessarily loggers.

#include <boost/log/utility/manipulators/auto_newline.hpp>

Sometimes it can be useful to be able to insert a newline character in the output stream, but only if it hasn't been inserted as part of the previous output. For example, if a string may or may not end with a newline, and we cannot easily tell which one it is each time. The auto_newline manipulator can be used to ensure that all such strings are reliably terminated with a newline and there are no duplicate newline characters. The manipulator will insert a newline unless the last character inserted into the stream before it was a newline. Its use is similar to standard stream manipulators:

BOOST_LOG(lg) << "Parameter: " << param.name << ", value: " << param.value << logging::auto_newline;

	Note
	This manipulator inspects previous output to the stream, and therefore can only be used with Boost.Log streams based on basic_formatting_ostream.

#include <boost/log/utility/manipulators/range.hpp>

It can be useful to be able to output elements of a container (or, more generally, a range), preferably separated with a delimiter. The range_manip manipulator allows to do this:

std::vector< int > ints{ 1, 2, 3 };

BOOST_LOG(lg) << "Integers: { " << logging::range_manip(ints, ", ") << " }"; // Outputs: "Integers: { 1, 2, 3 }"

	Tip
	This manipulator can also be used with regular output streams, not necessarily loggers.

Here, range_manip accepts two arguments - the range of elements, and, optionally, a delimiter. The range can be any type supported by Boost.Range begin() and end() free functions, which includes any standard containers and arrays. Elements of the range must support stream insertion operator. The delimiter argument, if specified, is inserted into stream between elements. The delimiter can be any type that supports stream insertion. If delimiter is not specified, the elements are output into the stream without separation.

#include <boost/log/utility/manipulators/tuple.hpp>

Tuple manipulator allows to output elements of a heterogeneous sequence (put simply, a tuple) to a stream, possibly separated with a delimiter. For example:

#include <boost/fusion/include/std_tuple.hpp>

std::tuple< std::string, int, char > address{ "Baker Street", 221, 'b' };

BOOST_LOG(lg) << "Address: " << logging::tuple_manip(address, ", "); // Outputs: "Address: Baker Street, 221, b"

	Note
	In order to support different types of sequences, users may need to #include additional support headers from Boost.Fusion, like boost/fusion/include/std_tuple.hpp in this example. See Boost.Fusion documentation.

	Tip
	This manipulator can also be used with regular output streams, not necessarily loggers.

Here, tuple_manip accepts two arguments - the sequence of elements, and, optionally, a delimiter. The heterogeneous sequence can be any sequence supported by Boost.Fusion, for example std::pair, std::tuple, boost::tuple, boost::fusion::vector or any structure that has been adapted using one of the BOOST_FUSION_ADAPT* macros. Elements of the sequence must support stream insertion operator. The delimiter argument, if specified, is inserted into stream between elements. The delimiter can be any type that supports stream insertion. If delimiter is not specified, the elements are output into the stream without separation.

	Tip
	You can also use tuples generated by std::tie or boost::tie with this manipulator, which allows unified formatting of disjoint variables without having to copy them into a structure.

#include <boost/log/utility/manipulators/optional.hpp>

Optional manipulator allows to output an optional value to the output stream. If the value is not present, the manipulator allows to specify a "none" marker to output instead. For example:

boost::optional< int > param1;
boost::optional< int > param2 = 10;

BOOST_LOG(lg) << "param1: " << logging::optional_manip(param1, "[none]") << ", param2: " << logging::optional_manip(param2, "[none]"); // Outputs: "param1: [none], param2: 10"

	Tip
	This manipulator can also be used with regular output streams, not necessarily loggers.

Here, optional_manip accepts two arguments - the optional value, and, optionally, a "none" marker. The optional value can be any type that supports the following:

Examples of types that fit these requirements are boost::optional (see Boost.Optional), std::optional and pointers to objects.

The "none" marker argument, if specified, is inserted into stream in case if the optional value is not present (i.e. the contextual conversion to bool yields false). The marker can be any type that supports stream insertion. If the marker is not specified, no output is produced if the value is not present.

#include <boost/log/utility/manipulators/invoke.hpp>

Invoke manipulator allows to inject a user-defined function call into the stream output expression. The function will be called when the manipulator is inserted into the stream. The manipulator will pass a reference to the stream to the function as the first argument, optionally followed by a number of additional arguments that were specified on the manipulator construction. For example:

void print_signal(std::ostream& stream, int sig)
{
    switch (sig)
    {
    case SIGINT:
        stream << "SIGINT";
        break;
    case SIGTERM:
        stream << "SIGTERM";
        break;
    default:
        stream << sig;
        break;
    }
}

int sig = SIGINT;

// Outputs: "Signal received: SIGINT"
BOOST_LOG(lg) << "Signal received: " << logging::invoke_manip(&print_signal, sig);

	Tip
	This manipulator can also be used with regular output streams, not necessarily loggers.

Here, print_signal will be called by the manipulator when its operator<< is called. The output stream will be passed as the first argument and any additional arguments (sig, in this case) following that. The arguments are captured by value by default. One can use std::ref/boost::ref if capturing by reference is needed.

	Note
	Passing additional arguments to the function requires a C++14 compiler. Use std::bind, Boost.Bind or C++11 lambdas to bind arguments to the function instead of passing them separately if lower C++ version is required.

Please note that the function will be called only if the streaming expression is executed. If the log record is discarded by filters, the streaming expression is skipped and the user's function is not called. Do not use this manipulator for injecting business-critical calls into logging expressions.

This manipulator is especially convenient with C++11 lambdas. The above example could be rewritten like this:

int sig = SIGINT;

// Outputs: "Signal received: SIGINT"
BOOST_LOG(lg) << "Signal received: " << logging::invoke_manip([sig](auto& stream)
{
    switch (sig)
    {
    case SIGINT:
        stream << "SIGINT";
        break;
    case SIGTERM:
        stream << "SIGTERM";
        break;
    default:
        stream << sig;
        break;
    }
});

#include <boost/log/utility/ipc/object_name.hpp>

In modern operating systems process-shared system resources are typically identified with names. Unfortunately, different systems have different requirements on the name syntax and allowed character set. Additionally, some systems offer support for namespaces in order to avoid name clashes. The object_name class is intended to hide these differences.

An object name can be constructed from a UTF-8 string identifier and a scope. A portable identifier can contain the following characters:

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
a b c d e f g h i j k l m n o p q r s t u v w x y z
0 1 2 3 4 5 6 7 8 9 . _ -

	Note
	The character set corresponds to POSIX Portable Filename Character Set.

Use of other characters may result in non-portable system-specific behavior.

The scope is identified with the object_name::scope enumeration:

The scopes are not overlapping. For instance, if an object is created in the global scope, the object cannot be opened with the same name but in user's scope. Some of the scopes may require elevated privileges to create or open objects in.

	Warning
	Object name scoping should not be considered a security measure. Objects may still be accessible by processes outside of their name scopes. The main purpose of the scopes is to avoid name clashes between different processes using object_name. Use access permissions for security control.

#include <boost/log/utility/ipc/reliable_message_queue.hpp>

The reliable_message_queue class implements a reliable one-way channel of passing messages from one or multiple writers to a single reader. The format of the messages is user-defined and must be consistent across all writers and the reader. The queue does not enforce any specific format of the messages, other than they should be supplied as a contiguous array of bytes. The queue internally uses a process-shared storage identified by an object name (the queue name).

The queue storage is organized as a fixed number of blocks of a fixed size. The block size must be an integer power of 2 and is expressed in bytes. Each written message, together with some metadata added by the queue, consumes an integer number of blocks. Each read message received by the reader releases the blocks allocated for that message. As such the maximum size of a message is slightly less than block size times capacity of the queue. For efficiency, it is recommended to choose block size large enough to accommodate most of the messages to be passed through the queue. The queue is considered empty when no messages are enqueued (all blocks are free). The queue is considered full at the point of enqueueing a message when there is not enough free blocks to accommodate the message.

The queue is reliable in that it will not drop successfully sent messages that are not received by the reader, other than the case when a non-empty queue is destroyed by the last user. If a message cannot be enqueued by the writer because the queue is full, the queue will act depending on the overflow policy specified at the queue creation:

The policy is object local, i.e. different writers and the reader can have different overflow policies. Here is an example of writing to the message queue:

int main()
{
    typedef logging::ipc::reliable_message_queue queue_t;

    // Create a message_queue_type object that is associated with the interprocess
    // message queue named "ipc_message_queue".
    queue_t queue
    (
        keywords::name = logging::ipc::object_name(logging::ipc::object_name::user, "ipc_message_queue"),
        keywords::open_mode = logging::open_mode::open_or_create,  
        keywords::capacity = 256,                                  
        keywords::block_size = 1024,                               
        keywords::overflow_policy = queue_t::fail_on_overflow      
    );

    // Send a message through the queue
    std::string message = "Hello, Viewer!";
    queue_t::operation_result result = queue.send(message.data(), static_cast< queue_t::size_type >(message.size()));

    // See if the message was sent
    switch (result)
    {
    case queue_t::operation_result::succeeded:
        std::cout << "Message sent successfully" << std::endl;
        break;

    case queue_t::operation_result::no_space:
        std::cout << "Message could not be sent because the queue is full" << std::endl;
        break;

    case queue_t::operation_result::aborted:
        // This can happen is overflow_policy is block_on_overflow
        std::cout << "Message sending operation has been interrupted" << std::endl;
        break;
    }

    return 0;
}

See the complete code.

Typically, the queue would be used for sending log records to a different process. As such, instead of using the queue for writing directly, one would use a special sink backend for that. See text_ipc_message_queue_backend documentation.

Receiving messages from the queue is similar. Here is an example of a log viewer that receives messages from the queue and displays them on the console.

int main()
{
    try
    {
        typedef logging::ipc::reliable_message_queue queue_t;

        // Create a message_queue_type object that is associated with the interprocess
        // message queue named "ipc_message_queue".
        queue_t queue
        (
            keywords::name = logging::ipc::object_name(logging::ipc::object_name::user, "ipc_message_queue"),
            keywords::open_mode = logging::open_mode::open_or_create,
            keywords::capacity = 256,
            keywords::block_size = 1024,
            keywords::overflow_policy = queue_t::block_on_overflow
        );

        std::cout << "Viewer process running..." << std::endl;

        // Keep reading log messages from the associated message queue and print them on the console.
        // queue.receive() will block if the queue is empty.
        std::string message;
        while (queue.receive(message) == queue_t::succeeded)
        {
            std::cout << message << std::endl;

            // Clear the buffer for the next message
            message.clear();
        }
    }
    catch (std::exception& e)
    {
        std::cout << "Failure: " << e.what() << std::endl;
    }

    return 0;
}

See the complete code.

	Note
	The queue does not guarantee any particular order of received messages from different writer threads. Messages sent by a particular writer thread will be received in the order of sending.

A blocked reader or writer can be unblocked by calling stop_local. After this method is called, all threads blocked on this particular object are released and return operation_result::aborted. The other instances of the queue (in the current or other processes) are unaffected. In order to restore the normal functioning of the queue instance after the stop_local call the user has to invoke reset_local.

#include <boost/log/utility/setup/console.hpp>
#include <boost/log/utility/setup/file.hpp>
#include <boost/log/utility/setup/common_attributes.hpp>

The library provides a number of functions that simplify some common initialization procedures, like sink and commonly used attributes registration. This is not much functionality. However, it saves a couple of minutes of learning the library for a newcomer.

Logging to the application console is the simplest way to see the logging library in action. To achieve this, one can initialize the library with a single function call, like this:

int main(int, char*[])
{
    // Initialize logging to std::clog
    logging::add_console_log();

    // Here we go, we can write logs right away
    src::logger lg;
    BOOST_LOG(lg) << "Hello world!";

    return 0;
}

Pretty easy, isn't it? There is also the wadd_console_log function for wide-character console. If you want to put logs to some other standard stream, you can pass the stream to the add_console_log function as an argument. E.g. enabling logging to std::cout instead of std::clog would look like this:

logging::add_console_log(std::cout);

What's important, is that you can further manage the console sink if you save the shared_ptr to the sink that this function returns. This allows you to set up things like filter, formatter and auto-flush flag.

int main(int, char*[])
{
    // Initialize logging to std::clog
    boost::shared_ptr<
        sinks::synchronous_sink< sinks::text_ostream_backend >
    > sink = logging::add_console_log();

    sink->set_filter(expr::attr< int >("Severity") >= 3);
    sink->locked_backend()->auto_flush(true);

    // Here we go, we can write logs right away
    src::logger lg;
    BOOST_LOG(lg) << "Hello world!";

    return 0;
}

Similarly to console, one can use a single function call to enable logging to a file. All you have to do is to provide the file name:

int main(int, char*[])
{
    // Initialize logging to the "test.log" file
    logging::add_file_log("test.log");

    // Here we go, we can write logs right away
    src::logger lg;
    BOOST_LOG(lg) << "Hello world!";

    return 0;
}

The add_console_log and add_file_log functions do not conflict and may be combined freely, so it is possible to set up logging to the console and a couple of files, including filtering and formatting, in about 10 lines of code.

Lastly, there is an add_common_attributes function that registers two frequently used attributes: "LineID" and "TimeStamp". The former counts log record being made and has attribute value unsigned int. The latter, as its name implies, provides the current time for each log record, in the form of boost::posix_time::ptime (see Boost.DateTime). These two attributes are registered globally, so they will remain available in all threads and loggers. This makes the final version of our code sample look something like this:

int main(int, char*[])
{
    // Initialize sinks
    logging::add_console_log()->set_filter(expr::attr< int >("Severity") >= 4);

    logging::formatter formatter =
        expr::stream
            << expr::attr< unsigned int >("LineID") << ": "
            << expr::format_date_time< boost::posix_time::ptime >("TimeStamp", "%Y-%m-%d %H:%M:%S") << " *"
            << expr::attr< int >("Severity") << "* "
            << expr::message;

    logging::add_file_log("complete.log")->set_formatter(formatter);

    boost::shared_ptr<
        sinks::synchronous_sink< sinks::text_ostream_backend >
    > sink = logging::add_file_log("essential.log");
    sink->set_formatter(formatter);
    sink->set_filter(expr::attr< int >("Severity") >= 1);

    // Register common attributes
    logging::add_common_attributes();

    // Here we go, we can write logs
    src::logger lg;
    BOOST_LOG(lg) << "Hello world!";

    return 0;
}

#include <boost/log/utility/setup/filter_parser.hpp>
#include <boost/log/utility/setup/formatter_parser.hpp>

Filter and formatter parsers allow constructing filters and formatters from a descriptive string. The function parse_filter is responsible for recognizing filters and parse_formatter - for recognizing formatters.

In the case of filters the string is formed of a sequence of condition expressions, interconnected with boolean operations. There are two operations supported: conjunction (designated as "&" or "and") and disjunction ("|" or "or"). Each condition itself may be either a single condition or a sub-filter, taken in round brackets. Each condition can be negated with the "!" sign or "not" keyword. The condition, if it's not a sub-filter, usually consists of an attribute name enclosed in percent characters ("%"), a relation keyword and an operand. The relation and operand may be omitted, in which case the condition is assumed to be the requirement of the attribute presence (with any type).

filter:
    condition { op condition }

op:
    &
    and
    |
    or

condition:
    !condition
    not condition
    (filter)
    %attribute_name%
    %attribute_name% relation operand

relation:
    >
    <
    =
    !=
    >=
    <=
    begins_with
    ends_with
    contains
    matches

Below are some examples of filters:

The formatter string syntax is even simpler and pretty much resembles Boost.Format format string syntax. The string is interpreted as a template which can contain attribute names enclosed with percent signs ("%"). The corresponding attribute values will replace these placeholders when the formatter is applied. The placeholder "%Message%" will be replaced with the log record text. For instance, the following formatter string:

[%TimeStamp%] *%Severity%* %Message%

will make log records look like this:

[2008-07-05 13:44:23] *0* Hello world

	Note
	Previous releases of the library also supported the "%_%" placeholder for the message text. This placeholder is deprecated now, although it still works for backward compatibility. Its support will be removed in future releases.

It must be noted that by default the library only supports those attribute value types which are known at the library build time. User-defined types will not work properly in parsed filters and formatters until registered in the library. It is also possible to override formatting rules of the known types, including support for additional formatting parameters in the string template. More on this is available in the Extending the library section.

Note

The parsed formatters and filters are generally less optimal than the equivalent ones written in code with template expressions. This is because of two reasons: (*) the programmer usually knows more about types of the attribute values that may be involved in formatting or filtering and (*) the compiler has a better chance to optimize the formatter or filter if it is known in compile time. Therefore, when performance matters, it is advised to avoid parsed filters and formatters.

#include <boost/log/utility/setup/settings.hpp>
#include <boost/log/utility/setup/from_settings.hpp>

The headers define components for library initialization from a settings container. The settings container is basically a set of named parameters divided into sections. The container is implemented with the basic_settings class template. There are several constraints on how parameters are stored in the container:

So basically, settings container is a layered associative container, with string keys and values. In some respect it is similar to Boost.PropertyTree, and in fact it supports construction from boost::ptree. The supported parameters are described below.

	Tip
	In the tables below, the CharT type denotes the character type that is used with the settings container.

Sink settings are divided into separate subsections within the common top-level section "Sinks" - one subsection for each sink. The subsection names denote a user-defined sink name. For example, "MyFile".

Note

Previous versions of the library also supported top-level sections starting with the "Sink:" prefix to describe sink parameters. This syntax is deprecated now, although it still works when parsing a settings file for backward compatibility. The parser will automatically put these sections under the "Sinks" top-level section in the resulting settings container. Support for this syntax will be removed in future releases.

Besides the common settings that all sinks support, some sink backends also accept a number of specific parameters. These parameters should be specified in the same section.

	Warning
	The text file sink uses Boost.Filesystem internally, which may cause problems on process termination. See here for more details.

The time-based rotation can be set up with one of the two parameters: RotationInterval or RotationTimePoint. Not more than one of these parameters should be specified for a given sink. If none is specified, no time-based rotation will be performed.

The RotationTimePoint parameter should have one of the following formats, according to the Boost.DateTime format notation:

The user is free to fill the settings container from whatever settings source he needs. The usage example is below:

logging::settings setts;

setts["Core"]["Filter"] = "%Severity% >= warning";
setts["Core"]["DisableLogging"] = false;

// Subsections can be referred to with a single path
setts["Sinks.Console"]["Destination"] = "Console";
setts["Sinks.Console"]["Filter"] = "%Severity% >= critical";
setts["Sinks.Console"]["Format"] = "%TimeStamp% [%Severity%] %Message%";
setts["Sinks.Console"]["AutoFlush"] = true;

// ...as well as the individual parameters
setts["Sinks.File.Destination"] = "TextFile";
setts["Sinks.File.FileName"] = "MyApp_%3N.log";
setts["Sinks.File.AutoFlush"] = true;
setts["Sinks.File.RotationSize"] = 10 * 1024 * 1024; // 10 MiB
setts["Sinks.File.Format"] = "%TimeStamp% [%Severity%] %Message%";

logging::init_from_settings(setts);

See the complete code.

	Note
	Initialization from settings does not automatically create any attributes or loggers, the application developer is still responsible for creating those. It can be said that loggers and attributes define the data that is exported by the application and the settings only describe how that data is going to be presented to the application user.

The settings reader also can be extended to support custom sink types. See the Extending the library section for more information.

#include <boost/log/utility/setup/from_stream.hpp>

Support for configuration files is a frequently requested feature of the library. And despite the fact there is no ultimately convenient and flexible format of the library settings, the library provides preliminary support for this feature. The functionality is implemented with a simple function init_from_stream, which accepts a std::istream and reads the library settings from it. The function then passes on the read settings to the init_from_settings function, described above. Therefore the parameter names and their meaning is the same as for the init_from_settings function.

The settings format is quite simple and widely used. Below is the description of syntax and parameters.

# Comments are allowed. Comment line begins with the '#' character
# and spans until the end of the line.

# Logging core settings section. May be omitted if no parameters specified within it.
[Core]
DisableLogging=false
Filter="%Severity% > 3"

# Sink settings sections
[Sinks.MySink1]

# Sink destination type
Destination=Console

# Sink-specific filter. Optional, by default no filter is applied.
Filter="%Target% contains \"MySink1\""

# Formatter string. Optional, by default only log record message text is written.
Format="<%TimeStamp%> - %Message%"

# The flag shows whether the sink should be asynchronous
Asynchronous=false

# Enables automatic stream flush after each log record.
AutoFlush=true

Here's the usage example:

int main(int, char*[])
{
    // Read logging settings from a file
    std::ifstream file("settings.ini");
    logging::init_from_stream(file);

    return 0;
}

See a more complete example.