SocketError

An error surfaced by SocketAddress, Socket, and ServerSocket operations.

enum SocketError

Mentioned In

Overview

SocketError is the sole error type thrown by the idiomatic Event API for TCP I/O and address parsing. Every case carries either a user-supplied string (for input-validation failures) or the raw errno value captured at the point of failure, so callers can disambiguate transient conditions (e.g. EINPROGRESS, EAGAIN) from permanent failures (e.g. ECONNREFUSED).

Interpreting the errno payload

The Int32 payload attached to .connectionFailed, .bindFailed, .listenFailed, .acceptFailed, .readFailed, .writeFailed, and .socketCreationFailed is the value of errno immediately after the failing connect(2) / bind(2) / listen(2) / accept(2) / read(2) / write(2) / socket(2) syscall. It is not a POSIX abstraction — it is the platform’s raw errno. To render a human-readable string, pass it through strerror(_:); the default errorDescription does this for you.

When each case is thrown

SocketError.invalidAddress(_:) — ipv4(_:port:) or ipv6(_:port:) rejected the input string. The payload is the original host string.
SocketError.socketCreationFailed(_:) — socket(2) failed inside connect(to:port:loop:) or listen(port:backlog:loop:).
SocketError.connectionFailed(_:) — connect(2) returned a non-EINPROGRESS error, or the socket’s pending-write event reported failure.
SocketError.bindFailed(_:) / SocketError.listenFailed(_:) — server-socket setup failed after socket creation.
SocketError.acceptFailed(_:) — accept(2) on a ServerSocket returned a negative value.
SocketError.readFailed(_:) / SocketError.writeFailed(_:) — the underlying read(2) / write(2) returned a negative value.
SocketError.connectionClosed — read(2) returned 0 (orderly shutdown by peer).
SocketError.timeout — reserved for future timeout-based APIs; not emitted today.

See Also

Production Considerations for the current caveat list, including behaviors not yet wrapped (UDP, TLS, timeouts, cancellation).