Error conditions originating from the operating system or other low-level
application program interfaces (API's) are typically reported via an integer
representing an error code. When these low-level API calls are wrapped in
portable code, such as in a portable library, some users want to deal with the
error codes in portable ways. Other users need to get at the system specific
error codes, so they can deal with system specific needs. The Boost System
library provides simple, light-weight
error_code objects that encapsulate system-specific error code values, yet
also provide access to more abstract and portable error conditions via
error_condition objects.
Because error_code objects can represent errors from sources other than the
operating system, including user-defined sources, each error_code and
error_condition has an associated
error_category.

An exception class,
system_error, is provided. Derived from std::runtime_error, it captures the
underlying error_code for the problem causing the exception so that this
important information is not lost.

While exceptions are the preferred C++ default error code reporting
mechanism, users of libraries dependent on low-level API's often need overloads
reporting error conditions via error code arguments and/or return values rather
than via throwing exceptions. Otherwise, when errors are not exceptional
occurrences and must be dealt with as they arise, programs become littered with
try/catch blocks, unreadable, and very inefficient. The Boost System library
supports both error reporting by exception and by error code.

In addition to portable errors codes and conditions supported by the
error_code.hpp header, system-specific headers support the Cygwin, Linux,
and Windows platforms. These headers are effectively no-ops if included for
platforms other than their intended target.

The Boost System Library will become part of the C++0x Standard Library.
A number of changes, particularly to names, were made by the C++ committee
during standardization. The Boost implementation is tracking those changes.
See Deprecated names for
synonyms provided to prevent breakage of existing user code. See
Breaking changes for changes
that unavoidably break existing user code. All breaking changes are noisy
and will cause compile-time errors.

Class error_code and error_condition are designed as a value types so
they can be copied
without slicing and do not requiring heap allocation, but still have polymorphic
behavior based on the error category. This is achieved by abstract base class
error_category supplying the polymorphic behavior, and
error_code and error_condition containing a pointer to an object of a type derived from
error_category.

Many of the detailed design decisions were driven by the requirements that
users to be able to add additional error categories, and that it be no more
difficult to write portable code than system-specific code.

The operator<< overload for error_code eliminates a
misleading conversion to bool in code like cout << ec, where
ec is of type error_code. It is also useful in its own
right.

N1975, Filesystem Library Proposal for TR2, accepted for Library Technical
Report 2 (TR2) at the Berlin meeting, included additional components to
supplement the Standard Library's Diagnostics clause. Since then, these error
reporting components have received wider public scrutiny and enhancements have
been made to the design. The enhanced version has been used by N2054, Networking
Library Proposal for TR2, demonstrating that these error reporting components
are useful beyond the original Filesystem Library.

The original proposal viewed error categories as a binary choice between
errno (i.e. POSIX-style) and the native operating system's error
codes. The proposed components now allow as many additional error categories as
are needed by either implementations or by users. The need to support additional
error categories, for example, occurs in some networking library implementations
because they are built on top of the POSIX getaddrinfo API that
uses error codes not based on errno.

Christopher Kohlhoff and Peter Dimov made important contributions to the
design. Comments and suggestions were also received from Pavel Vozenilek,
Gennaro Prota, Dave Abrahams, Jeff Garland, Iain Hanson, Oliver Kowalke, and
Oleg Abrosimov. Christopher Kohlhoff suggested several improvements to the N2066
paper. Johan Nilsson's comments led to several of the refinements in N2066 .