////
Copyright 2003-2017 Beman Dawes
Copyright 2018, 2021 Peter Dimov

Distributed under the Boost Software License, Version 1.0.

See accompanying file LICENSE_1_0.txt or copy at
http://www.boost.org/LICENSE_1_0.txt
////

[#introduction]
# Introduction
:idprefix: intro_

Errors originating from the operating system or other low-level application
program interfaces (APIs) are typically reported via an integer representing
an error code, either by returning the code directly from the function (e.g.
`pthread_mutex_init`) or by using a side channel such as the `errno`
pseudo-variable under POSIX or `GetLastError()` under Windows.

However, these integer error values can only be interpreted when their source
is known. The value 5 under Windows means `ERROR_ACCESS_DENIED` when returned
by `GetLastError()`, but `EIO` when retrieved from `errno`. And conversely,
the same error condition "access denied" is represented by the value 5 when
returned by `GetLastError()` and 13 (`EACCES`) when retrieved from `errno`.

This means that in order for code to be able to handle errors from both
sources (to retrieve a text message describing the error, or to check whether
the error means "access denied"), it needs to know where the integer error
value originated. For this to be possible, the integer error value needs to
be accompanied by a piece of information identifying the source.

Boost.System provides a framework in which this is possible. Errors are
represented by a class `error_code` which contains both the error value and
a pointer to their source (called "category"), represented as a class derived
from `error_category`.

The category provides member functions such as `message`, which returns a text
message for a specific error value, and `equivalent`, which can be used to test
whether a specific error value correspond to an error condition such as "access
denied". `error_code` uses these category-provided functions in the
implementation of its `message` and `operator==` member functions.

Boost.System contains two predefined category classes, the generic category
(a reference to which is returned by `generic_category()`) and the system
category (`system_category()`). The generic category represents the error
values of the portable subset of `errno` values defined by the POSIX standard,
whereas the system category is OS dependent. Under POSIX, the system category
represents the `errno` values returned by the OS APIs (a superset of those in
the generic category), whereas under Windows, the system category represents
the error values returned by `GetLastError()`.

The framework is extensible. Users can define their own categories by
deriving a class from `error_category` and implementing a function that
returns a reference to an instance of it. This capability is useful both for
describing library-defined error values, and for adapting existing C API
libraries that return integer error values.

For those who prefer error reporting via exceptions, Boost.System provides
a standard exception class `system_error` that stores an `error_code`.

Boost.System was standardized in {cpp}11 as `<system_error>`. For a while,
the two were equivalent, but Boost.System has evolved since then and now
contains a number of extensions over its standard sibling:

* A non-allocating overload of `message`;
* Support for nonzero error codes meaning success, via the `failed` member
  functions;
* Support for 64 bit category identifiers, as a solution to the problem
  that sometimes it's not possible to ensure that only one instance of a
  category exists in the program;
* Support for attaching source locations (file/line/function) to error codes;
* A class `result<T>` that can be used to return either a value or an error
  code from a function;
* Various other minor improvements.

`boost::system::error_code` can be converted to, and constructed from,
`std::error_code`.