diff --git a/doc/system/introduction.adoc b/doc/system/introduction.adoc index 60afb85..fa141cd 100644 --- a/doc/system/introduction.adoc +++ b/doc/system/introduction.adoc @@ -1,6 +1,6 @@ //// Copyright 2003-2017 Beman Dawes -Copyright 2018 Peter Dimov +Copyright 2018, 2021 Peter Dimov Distributed under the Boost Software License, Version 1.0. @@ -12,39 +12,67 @@ http://www.boost.org/LICENSE_1_0.txt # Introduction :idprefix: intro_ -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. +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. -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`. +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`. -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. +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. -While exceptions are the preferred {cpp} 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 inefficient. The Boost System library -supports both error reporting by exception and by error code. +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`. -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 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 is part of the {cpp}11 Standard Library. -A number of changes, particularly to names, were made by the C++ committee -during standardization. The Boost implementation has been tracking those changes. -See <<#ref_deprecated_names,Deprecated Names>> for synonyms provided to prevent -breakage of existing user code. +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 ``. 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` 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`.