9 Error reporting [err.report]

9.1 Synchronous operations [err.report.sync]

Most synchronous network library functions provide two overloads, one that throws an exception to report system errors, and another that sets an error_code (C++ 2014 [syserr]).

Note: This supports two common use cases:

  • Uses where system errors are truly exceptional and indicate a serious failure. Throwing an exception is the most appropriate response.

  • Uses where system errors are routine and do not necessarily represent failure. Returning an error code is the most appropriate response. This allows application specific error handling, including simply ignoring the error.

 — end note ]

Functions not having an argument of type error_code& report errors as follows, unless otherwise specified:

  • When a call by the implementation to an operating system or other underlying API results in an error that prevents the function from meeting its specifications, the function exits via an exception of a type that would match a handler of type system_error.

  • Destructors throw nothing.

Functions having an argument of type error_code& report errors as follows, unless otherwise specified:

  • If a call by the implementation to an operating system or other underlying API results in an error that prevents the function from meeting its specifications, the error_code& argument ec is set as appropriate for the specific error. Otherwise, the ec argument is set such that !ec is true.

Where a function is specified as two overloads, with and without an argument of type error_code&:

R f(A1 a1, A2 a2, ..., AN aN);
R f(A1 a1, A2 a2, ..., AN aN, error_code& ec);

then, when R is non-void, the effects of the first overload are as if:

error_code ec;
R r(f(a1, a2, ..., aN, ec));
if (ec) throw system_error(ec, S);
return r;

otherwise, when R is void, the effects of the first overload are as if:

error_code ec;
f(a1, a2, ..., aN, ec);
if (ec) throw system_error(ec, S);

except that the type thrown may differ as specified above. S is an ntbs indicating where the exception was thrown. [ Note: A possible value for S is __func__.  — end note ]

For both overloads, failure to allocate storage is reported by throwing an exception as described in the C++ standard (C++ 2014 [res.on.exception.handling]).

In this document, when a type requirement is specified using two function call expressions f, with and without an argument ec of type error_code:

f(a1, a2, ..., aN)
f(a1, a2, ..., aN, ec)

then the effects of the first call expression of f shall be as described for the first overload above.

9.2 Asynchronous operations [err.report.async]

Asynchronous network library functions in this document are identified by having the prefix async_ and take a completion handler ([async.reqmts.async.token]). These asynchronous operations report errors as follows:

  • If a call by the implementation to an operating system or other underlying API results in an error that prevents the asynchronous operation from meeting its specifications, the completion handler is invoked with an error_code value ec that is set as appropriate for the specific error. Otherwise, the error_code value ec is set such that !ec is true.

  • Asynchronous operations shall not fail with an error condition that indicates interruption of an operating system or underlying API by a signal. [ Note: Such as POSIX error number EINTR  — end note ] Asynchronous operations shall not fail with any error condition associated with non-blocking operations. [ Note: Such as POSIX error numbers EWOULDBLOCK, EAGAIN, or EINPROGRESS; Windows error numbers WSAEWOULDBLOCK or WSAEINPROGRESS  — end note ]

In this document, when a type requirement is specified as a call to a function or member function having the prefix async_, then the function shall satisfy the error reporting requirements described above.

9.3 Error conditions [err.report.conditions]

Unless otherwise specified, when the behavior of a synchronous or asynchronous operation is defined “as if” implemented by a POSIX function, the error_code produced by the function shall meet the following requirements:

  • If the failure condition is one that is listed by POSIX for that function, the error_code shall compare equal to the error's corresponding enum class errc (C++ 2014 [syserr]) or enum class resolver_errc ([internet.resolver.err]) constant.

  • Otherwise, the error_code shall be set to an implementation-defined value that reflects the underlying operating system error.

Example: The POSIX specification for shutdown lists EBADF as one of its possible errors. If a function that is specified “as if” implemented by shutdown fails with EBADF then the following condition holds for the error_code value ec: ec == errc::bad_file_descriptor  — end example ]

When the description of a function contains the element Error conditions, this lists conditions where the operation may fail. The conditions are listed, together with a suitable explanation, as enum class constants. Unless otherwise specified, this list is a subset of the failure conditions associated with the function.

9.4 Suppression of signals [err.report.signal]

Some POSIX functions referred to in this document may report errors by raising a SIGPIPE signal. Where a synchronous or asynchronous operation is specified in terms of these POSIX functions, the generation of SIGPIPE is suppressed and an error condition corresponding to POSIX EPIPE is produced instead.