forked from boostorg/system
79 lines
3.8 KiB
Plaintext
79 lines
3.8 KiB
Plaintext
////
|
|
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`.
|