Boost.System: Extensible Error Reporting

Let’s suppose that we’re implementing a portable file wrapper over the OS file APIs. Its general outline is shown below:

Since we’re implementing the POSIX version of file, its data member is a POSIX file descriptor int fd_;, although other implementations will differ.

Our read and write functions return the number of bytes transferred, and signal errors via the output parameter ec, of type boost::system::error_code.

An implementation of file::read might look like this:

We first call the POSIX API read; if it returns an error, we store the errno value in ec, using the system category, and return 0 as bytes transferred. Otherwise, we clear ec to signal success, and return the result of ::read.

Under POSIX, the system category corresponds to POSIX errno values, which is why we use it.

In principle, since the generic category also corresponds to errno values under all platforms, we could have used it here; however, by convention under POSIX, if the errno value comes from the OS (the "system"), we use the system category for it. That’s because the system category values may be a platform-specific superset of the generic (platform-independent) values.

The implementation of file::write is basically the same. We show it here for completeness:

Under Windows, our file object will store a HANDLE instead of an int:

and the implementation of file::read will look like this:

Here, the system category corresponds to the values defined in the system header <winerror.h> and returned by GetLastError(). Since we use the Win32 API ReadFile to implement file::read, and it returns the error code via GetLastError(), we again store that value in ec as belonging to the system category.

The implementation of file::write is, again, the same.

Our implementation of file::read has a problem; it accepts std::size_t values for size, but the behavior of ::read is unspecified when the requested value does not fit in ssize_t. To avoid reliance on unspecified behavior, let’s add a check for this condition and return an error:

In this case, since we’re returning the fixed errno value EINVAL, which is part of the portable subset defined by the generic category, we mark the error value in ec as belonging to the generic category.

It’s possible to use system as well, as EINVAL is also a system category value under POSIX; however, using the generic category for values belonging to the portable errno subset is slightly preferrable.

Our implementation of file::write needs to undergo a similar treatment. There, however, we’ll apply another change. When there’s no space left on the disk, ::write returns a number of bytes written that is lower than what we requested with size, but our function signals no error. We’ll make it return ENOSPC in this case.

We’ve used the system category to make it appear that the ENOSPC value has come from the ::write API, mostly to illustrate that this is also a possible approach. Using a generic value would have worked just as well.

Not much to say; the situation under Windows is exactly the same. The only difference is that we must use the generic category for returning errno values. The system category does not work; the integer values in the system category are entirely different from those in the generic category.

Unlike the standard <system_error>, Boost.System allows source locations (file/line/function) to be stored in error_code, so that functions handling the error can display or log the source code location where the error occurred. To take advantage of this functionality, our POSIX file::read function needs to be augmented as follows:

That is, before every ec.assign statement, we need to declare a static constexpr variable holding the current source location, then pass a pointer to it to assign. Since error_code is small and there’s no space in it for more than a pointer, we can’t just store the source_location in it by value.

BOOST_CURRENT_LOCATION is a macro expanding to the current source location (a combination of __FILE__, __LINE__, and BOOST_CURRENT_FUNCTION.) It’s defined and documented in Boost.Assert.

Under C++03, instead of static constexpr, one needs to use static const. Another option is BOOST_STATIC_CONSTEXPR, a Boost.Config macro that expands to either static constexpr or static const, as appropriate.

To avoid repeating this boilerplate each time we do ec.assign, we can define a macro:

which we can now use to augment, for example, the POSIX implementation of file::write:

Assuming that we have an error_code instance ec, returned to us by some function, we have a variety of means to obtain textual representations of the error code represented therein.

ec.to_string() gives us the result of streaming ec into a std::ostream, e.g. if std::cout << ec << std::endl; outputs system:6, this is what ec.to_string() will return. (system:6 under Windows is ERROR_INVALID_HANDLE from <winerror.h>.)

To obtain a human-readable error message corresponding to this code, we can use ec.message(). For ERROR_INVALID_HANDLE, it would give us "The handle is invalid" - possibly localized.

If ec contains a source location, we can obtain its textual representation via ec.location().to_string(). This will give us something like

if there is a location in ec, and

if there isn’t. (ec.has_location() is true when ec contains a location.)

Finally, ec.what() will give us a string that contains all of the above, something like

Most logging and diagnostic output that is not intended for the end user would probably end up using what(). (ec.what(), augmented with the prefix supplied at construction, is also what boost::system::system_error::what() would return.)

Let’s suppose that we need to implement a file copy function, with the following interface:

file_copy uses src.read to read bytes from src, then writes these bytes to dest using dest.write. This continues until one of these operations signals an error, or until end of file is reached. It returns the number of bytes written, and uses ec to signal an error.

Here is one possible implementation:

Note that there is no longer any difference between POSIX and Windows implementations; their differences are contained in file::read and file::write. file_copy is portable and works under any platform.

The general pattern in writing such higher-level functions is that they pass the output error_code parameter ec they received from the caller directly as the output parameter to the lower-level functions they are built upon. This way, when they detect a failure in an intermediate operation (by testing ec.failed()), they can immediately return to the caller, because the error code is already in its proper place.

Note that file_copy doesn’t even need to clear ec on success, by using ec = {};. Since we’ve already tested ec.failed(), we know that ec contains a value that means success.

Functions that signal errors via an output error_code& ec parameter require that the caller check ec after calling them, and take appropriate action (such as return immediately, as above.) Forgetting to check ec results in logic errors.

While this is a preferred coding style for some, others prefer exceptions, which one cannot forget to check.

An approach that has been introduced by Boost.Filesystem (which later turned into std::filesystem) is to provide both alternatives: a nonthrowing function taking error_code& ec, as file_copy above, and a throwing function that does not take an error_code output parameter, and throws exceptions on failure.

This is how this second throwing function is typically implemented:

That is, we simply call the nonthrowing overload of file_copy, and if it signals failure in ec, throw a system_error exception.

We use our function name __func__ ("file_copy") as the prefix, although that’s a matter of taste.

Note that typically under this style the overloads taking error_code& ec are decorated with noexcept, so that it’s clear that they don’t throw exceptions (although we haven’t done so in the preceding examples in order to keep the code C++03-friendly.)

Instead of providing two functions for every operation, an alternative approach is to make the function return sys::result<T> instead of T. result<T> is a class holding either T or error_code, similar to variant<T, error_code>.

Clients that prefer to check for errors and not rely on exceptions can test whether a result<T> r contains a value via if( r ) or its more verbose equivalent if( r.has_value() ), then obtain the value via *r or r.value(). If r doesn’t contain a value, the error_code it holds can be obtained with r.error().

Those who prefer exceptions just call r.value() directly, without checking. In the no-value case, this will automatically throw a system_error corresponding to the error_code in r.

Assuming our base file API is unchanged, this variation of file_copy would look like this:

The only difference here is that we return ec on error, instead of r.

Note, however, that we can no longer return both an error code and a number of transferred bytes; that is, we can no longer signal partial success. This is often not an issue at higher levels, but lower-level primitives such as file::read and file::write might be better off written using the old style.

Nevertheless, to demonstrate how result returning APIs are composed, we’ll show how file_copy would look if file::read and file::write returned result<size_t>:

Let’s suppose that we have called a function that signals failure using error_code, we have passed it an error_code variable ec, and now for some reason want to check whether the function has failed with an error code of EINVAL, "invalid argument".

Since error_code can be compared for equality, our first instict might be if( ec == error_code( EINVAL, generic_category() ).

This is wrong, and we should never do it.

First, under POSIX, the function might have returned EINVAL from the system category (because the error might have been returned by an OS API, and not by the function itself, as was the case in our read and write implementations.)

Since error_code comparisons are exact, EINVAL from the generic category does not compare equal to EINVAL from the system category.

(And before you start thinking about just comparing ec.value() to EINVAL, read on.)

Second, under Windows, the function might have returned error_code( ERROR_INVALID_PARAMETER, system_category() ). As we have already mentioned, the integer error values in the system category under Windows are completely unrelated to the integer errno values.

The correct approach is to compare ec not to specific error codes, but to error_condition( EINVAL, generic_category() ). Error conditions are a platform-independent way to represent the meaning of the concrete error codes. In our case, all error codes, under both POSIX and Windows, that represent EINVAL will compare equal to error_condition( EINVAL, generic_category() ).

In short, you should never compare error codes to error codes, and should compare them to error conditions instead. This is the purpose of the error_condition class, which is very frequently misunderstood.

Since

is a bit verbose, Boost.System provides enumerator values for the errno values against which an error code can be compared directly.

These enumerators are defined in <boost/system/errc.hpp>, and enable the above test to be written

which is what one should generally use for testing for a specific error condition, as a best practice.

Libraries with C (or extern "C") APIs often signal failure by returning a library-specific integer error code (with zero typically being reserved for "no error".) When writing portable C++ wrappers, we need to decide how to expose these error codes, and using error_code is a good way to do it.

Because the integer error codes are library specific, and in general match neither errno values or system category values, we need to define a library-specific error category.

Let’s suppose that we are writing a library libmyimg for reading some hypothetical image format, and that we have defined the following API function for that:

(using our portable file class from the preceding examples.)

Our hypothetical image format is simple, consisting of a fixed header, followed by the image data, so an implementation of load_image might have the following structure:

We can see that we need to define five error codes of our own. (Our function can also return other kinds of failures in ec — those will come from file::read which load_image_header will use to read the header.)

To define these errors, we’ll use a scoped enumeration type. (This example will take advantage of C++11 features.)

Boost.System supports being told that an enumeration type represents an error code, which enables implicit conversions between the enumeration type and error_code. It’s done by specializing the is_error_code_enum type trait, which resides in namespace boost::system like the rest of the library:

Once this is in place, we can now assign values of libmyimg::error to sys::error_code, which enables the implementation of load_image to be written as follows:

This is however not enough; we still need to define the error category for our enumerators, and associate them with it.

The first step follows our previous two examples very closely:

The second step involves implementing a function make_error_code in the namespace of our enumeration type error that takes error and returns boost::system::error_code:

Now load_image will compile, and we just need to fill the rest of its implementation with code that uses file::read to read the image data.

There’s one additional embellishment we can make. As we know, Boost.System was proposed for, and accepted into, the C++11 standard, and now there’s a standard implementation of it in <system_error>. We can make our error enumeration type compatible with std::error_code as well, by specializing the standard type trait std::is_error_code_enum:

This makes our enumerators convertible to std::error_code.

(The reason this works is that boost::system::error_code is convertible to std::error_code, so the return value of our make_error_code overload can be used to initialize a std::error_code.)

All of the libmyimg::error error codes we have so far represent the same error condition - invalid or unsupported image format. It might make sense to enable testing for this condition without the need to enumerate all five specific codes. To do this, we can define an error condition enumeration type:

which we can tag as representing an error condition by specializing is_error_condition_enum:

Similarly to the error code enumeration type, which needed a make_error_code overload, this one will need to have a make_error_condition overload, and a category.

It’s in principle possible to reuse the category we already defined for our error codes, by making the condition values start from, say, 10000 instead of 1. This saves some typing, but a better practice is to use a separate category for the error conditions. So that’s what we’ll do:

We have our condition, but it doesn’t do anything yet. To enable libmyimg::condition::invalid_format to compare equal to our error codes, we need to implement default_error_condition in the error code category:

That’s it; now ec == libmyimg::condition::invalid_format can be used to test whether ec contains one of our error codes corresponding to the "invalid image format" condition.

On a C++14 compiler, many Boost.System functions and member functions are now constexpr, and error_code and error_condition are literal classes.

In addition to enabling use in constant expressions (and constexpr functions), this significantly improves the quality of the generated code.

As a result of this change, however, now using Boost.System from C++14 or C++17 code requires that the library be also built with C++14 or above. This is the default on GCC 6 and newer, but not on GCC 5 or Clang. One can build Boost for C++14 by passing the cxxstd=14 option to b2.

(Previous versions allowed code built against any C++ standard to link with Boost.System built against any C++ standard. In 1.68, code using any C++ standard can link with Boost.System built with C++14 or above, but if Boost.System is built with C++11 or below, only code also built with C++11 and below can link to it successfully.)

On a C++11 compiler, Boost.System now provides implicit conversions from boost::system::error_category, error_code, and error_condition to their standard equivalents from <system_error>.

This allows libraries to expose a C++11 interface and report errors via std::error_code even when using Boost.System, directly or through a dependency such as Boost.ASIO.

The library is documented to use several C++11 and C++14 features, including noexcept, explicit conversion operators and constexpr. The actual implementation uses C++11 and C++14 features only when they are available, and otherwise falls back on C++03 features.

When BOOST_SYSTEM_ENABLE_DEPRECATED is defined, the library provides deprecated features for compatibility. These features are bound to eventually disappear.

When BOOST_SYSTEM_USE_UTF8 is defined, on Windows the library returns UTF-8 messages using code page CP_UTF8 instead of the default CP_ACP. This macro has no effect on POSIX.

When BOOST_SYSTEM_DISABLE_THREADS is defined, the library assumes that the current platform doesn’t support multiple threads and disables the use of the standard header <mutex>, eliminating the mutex locks. The single threaded libstdc++ is one such platform.

In the process of adding Boost.System to the C++11 standard library, the C++ committee changed some names. To ease transition, Boost.System deprecates the old names, but will provide them when the macro BOOST_SYSTEM_ENABLE_DEPRECATED is defined.