9 Error reporting [err.report]

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:

• (1.1)

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

• (1.2)

  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:

• (2.1)

  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.

• (2.2)

  Destructors throw nothing.

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

• (3.1)

  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.