Which Boost error codes/conditions are returned by which Boost.Asio calls?

Question

I am currently writing a TCP I/O facility that uses Boost.Asio as the underlying socket API, and I've noticed that Boost.Asio seems to lack documentation on which specific Boost error codes/conditions can result from each individual operation (e.g. function/method call or asynchronous operation). All that I've been able to find is the error code API and some informal error code lists, none of which correlate specific codes to specific operations.

This apparent lack of documentation is frustrating, because it's difficult to write robust code when you don't know the possible failure modes. It's impossible to even give examples, since I'm not even confident of which issues could arise from which operations due to the lack of documentation.

In comparison, the POSIX socket API is pretty decent at documenting failure modes. In particular, it lists errno and return values that can be generated by each function call.

Does this Boost.Asio documentation exist somewhere, and I'm just not seeing it? Or am I supposed to just guess at, reverse engineer, or collect empirical data on the failure modes of various parts of the Boost.Asio API in order to be able to write robust code that uses it?

Answer 1

In general, when Boost.Asio depends on the OS implementation, then it will neither specify the conditions under which errors may occur nor the error codes that may be returned. On failure Boost.Asio will populate a boost::system::error_code if the application is capable of receiving it, such as for asynchronous operations or synchronous operation overloads with the error_code parameter; otherwise it will throw an exception containing the error_code. The documentation states the following:

Unless otherwise noted, when the behaviour of an asynchronous operation is defined "as if" implemented by a POSIX function, the handler will be invoked with a value of type error_code that corresponds to the failure condition described by POSIX for that function, if any. Otherwise the handler will be invoked with an implementation-defined error_code value that reflects the operating system error.

Asynchronous operations will not fail with an error condition that indicates interruption by a signal (POSIX EINTR). Asynchronous operations will not fail with any error condition associated with non-blocking operations (POSIX EWOULDBLOCK, EAGAIN or EINPROGRESS; Windows WSAEWOULDBLOCK or WSAEINPROGRESS).

If error handling depends on the exact error code, then one can often use the BSD API mapping documentation to determine which OS calls are being made. One can then use the appropriate OS documentation to determine the conditions for which an error occurs and the values. The mapping between error codes and Boost.Asio error codes is located within asio/error.hpp, but the mapping is normally fairly straight forward.