The io::socket namespace provides a cross-platform abstraction for socket-level I/O operations. More...

Classes
struct	accept_t
	A tag type for the `io::accept` customization point object (CPO). More...

struct	bind_t
	A tag type for the `io::bind` customization point object (CPO). More...

struct	connect_t
	A tag type for the `io::connect` customization point object (CPO). More...

struct	fcntl_t
	A tag type for the `io::fcntl` customization point object (CPO). More...

struct	getpeername_t
	A tag type for the `io::getpeername` customization point object (CPO). More...

struct	getsockname_t
	A tag type for the `io::getsockname` customization point object (CPO). More...

struct	getsockopt_t
	A tag type for the `io::getsockopt` customization point object (CPO). More...

struct	listen_t
	A tag type for the `io::listen` customization point object (CPO). More...

struct	message_data
	A data structure that contains all the components of a socket message. More...

struct	recvmsg_t
	A tag type for the `io::recvmsg` customization point object (CPO). More...

struct	sendmsg_t
	A tag type for the `io::sendmsg` customization point object (CPO). More...

struct	setsockopt_t
	A tag type for the `io::setsockopt` customization point object (CPO). More...

struct	shutdown_t
	A tag type for the `io::shutdown` customization point object (CPO). More...

class	socket_address
	A platform-independent representation of a socket address. More...

class	socket_handle
	A thread-safe, move-only RAII wrapper for a native socket handle. More...

class	socket_message
	A thread-safe container for socket messages used in advanced I/O operations. More...

Typedefs
using	native_socket_type = int
	The native socket handle type for POSIX systems.

using	socket_buffer_type = std::span< char, std::dynamic_extent >
	The socket buffer type for POSIX systems.

using	socket_message_type = msghdr
	The socket message type for POSIX systems.

using	sockaddr_type = sockaddr
	The generic socket address structure for POSIX systems.

using	sockaddr_storage_type = sockaddr_storage
	The socket address storage structure for POSIX systems.

using	socklen_type = socklen_t
	The type used to represent socket-related sizes on POSIX systems.

using	ancillary_buffer = std::vector< char >
	Type alias for ancillary data buffer used in socket messages.

using	scatter_gather_buffer = std::vector< socket_buffer_type >
	Type alias for scatter-gather I/O buffer collection.

Functions
auto	close (native_socket_type socket) noexcept -> int
	Closes a socket descriptor on POSIX systems.

template<typename... Args>
auto	fcntl (native_socket_type socket, int cmd, Args &&...args) noexcept -> int
	Provides a C++ wrapper for the POSIX `fcntl` function.

auto	sendmsg (native_socket_type socket, const socket_message_type *msg, int flags) noexcept -> std::streamsize
	Sends a message on a socket.

auto	recvmsg (native_socket_type socket, socket_message_type *msg, int flags) noexcept -> std::streamsize
	Receives a message from a socket.

auto	tag_invoke (bind_t, const socket_handle &socket, const sockaddr_type *addr, socklen_type len) -> int
	Binds a socket to a local address.

auto	tag_invoke (bind_t, const socket_handle &socket, const socket_address &addr) -> int
	Binds a socket to a local address.

auto	tag_invoke (listen_t, const socket_handle &socket, int backlog) -> int
	Sets a socket to listen for incoming connections.

auto	tag_invoke (connect_t, const socket_handle &socket, const sockaddr_type *addr, socklen_type len) -> int
	Connects a socket to a remote address.

auto	tag_invoke (connect_t, const socket_handle &socket, const socket_address &addr) -> int
	Connects a socket to a remote address.

auto	tag_invoke (accept_t, const socket_handle &socket, sockaddr_type addr, socklen_type len) -> native_socket_type
	Accepts an incoming connection on a listening socket.

auto	tag_invoke (accept_t, const socket_handle &socket, socket_address addr={}) -> std::tuple< socket_handle, socket_address >
	Accepts an incoming connection on a listening socket.

auto	tag_invoke (sendmsg_t, const socket_handle &socket, const socket_message_type *msg, int flags) -> std::streamsize
	Sends a message on a socket.

auto	tag_invoke (sendmsg_t, const socket_handle &socket, const socket_message &msg) -> std::streamsize
	Sends a message on a socket using a `socket_message` object.

auto	tag_invoke (recvmsg_t, const socket_handle &socket, socket_message_type *msg, int flags) -> std::streamsize
	Receives a message from a socket.

auto	tag_invoke (getsockopt_t, const socket_handle &socket, int level, int optname, void optval, socklen_type optlen) -> int
	Gets a socket option.

auto	tag_invoke (setsockopt_t, const socket_handle &socket, int level, int optname, const void *optval, socklen_type optlen) -> int
	Sets a socket option.

auto	tag_invoke (getsockname_t, const socket_handle &socket, sockaddr_type addr, socklen_type len) -> int
	Gets the local address of a socket.

auto	tag_invoke (getpeername_t, const socket_handle &socket, sockaddr_type addr, socklen_type len) -> int
	Gets the peer address of a connected socket.

auto	tag_invoke (shutdown_t, const socket_handle &socket, int how) -> int
	Shuts down a socket connection.

template<typename... Args>
auto	tag_invoke (fcntl_t tag, const socket_handle &socket, int cmd, Args &&...args) -> int
	Performs a file control operation on a socket.

auto	swap (socket_handle &lhs, socket_handle &rhs) noexcept -> void

auto	swap (socket_message &lhs, socket_message &rhs) noexcept -> void

Detailed Description

The io::socket namespace provides a cross-platform abstraction for socket-level I/O operations.

This namespace contains a set of functions that wrap the underlying platform-specific socket APIs, providing a consistent and easy-to-use interface for socket programming.

Typedef Documentation

◆ ancillary_buffer

using io::socket::ancillary_buffer = typedef std::vector<char>

Type alias for ancillary data buffer used in socket messages.

This buffer stores control information that can be passed alongside the main message data in advanced socket operations. Ancillary data can include file descriptors, credentials, socket options, or other metadata that needs to be transmitted with the message.

See also: sendmsg(2), recvmsg(2), cmsg(3)

Definition at line 50 of file socket_message.hpp.

◆ native_socket_type

typedef::SOCKET io::socket::native_socket_type

The native socket handle type for POSIX systems.

The native socket handle type for Windows systems.

This is an alias for the int type, which is used as the underlying socket descriptor on POSIX systems.

This is an alias for the ::SOCKET type provided by the Winsock library.

Definition at line 38 of file socket.hpp.

◆ scatter_gather_buffer

using io::socket::scatter_gather_buffer = typedef std::vector<socket_buffer_type>

Type alias for scatter-gather I/O buffer collection.

This collection holds multiple data buffers that can be used for vectored I/O operations. Scatter-gather I/O allows reading from or writing to multiple non-contiguous memory regions in a single system call, improving performance by reducing the number of system calls needed for complex data structures.

See also: readv(2), writev(2), sendmsg(2), recvmsg(2)

Definition at line 63 of file socket_message.hpp.

◆ sockaddr_storage_type

typedef::SOCKADDR_STORAGE io::socket::sockaddr_storage_type

The socket address storage structure for POSIX systems.

The socket address storage structure for Windows systems.

This is an alias for the sockaddr_storage structure, which is used to store socket address information in a generic way, large enough to accommodate all supported socket address types.

This is an alias for the ::SOCKADDR_STORAGE type, which is used to store socket address information in a generic way, large enough to accommodate all supported socket address types.

Definition at line 146 of file socket.hpp.

◆ sockaddr_type

typedef::SOCKADDR io::socket::sockaddr_type

The generic socket address structure for POSIX systems.

The generic socket address structure for Windows systems.

This is an alias for the sockaddr structure, which serves as the base structure for all other socket address types (e.g., sockaddr_in). It is primarily used for type-casting when passing addresses to socket functions.

This is an alias for the ::SOCKADDR type, which serves as the base structure for all other socket address types (e.g., SOCKADDR_IN). It is primarily used for type-casting when passing addresses to Winsock functions.

Definition at line 137 of file socket.hpp.

◆ socket_buffer_type

typedef std::span< char, std::dynamic_extent > io::socket::socket_buffer_type

The socket buffer type for POSIX systems.

The socket buffer type for Windows systems.

Definition at line 56 of file socket.hpp.

◆ socket_message_type

typedef::WSAMSG io::socket::socket_message_type

The socket message type for POSIX systems.

The socket message type for Windows systems.

This is an alias for the msghdr structure, which is used for advanced socket I/O operations.

This is an alias for the ::WSAMSG type provided by the Winsock library.

Definition at line 64 of file socket.hpp.

◆ socklen_type

typedef int io::socket::socklen_type

The type used to represent socket-related sizes on POSIX systems.

The type used to represent socket-related sizes on Windows systems.

This is an alias for the socklen_t type, which is used for the lengths of socket address structures and other size parameters in POSIX socket functions.

This is an alias for the int type, which is used for the lengths of socket address structures and other size parameters in Winsock functions.

Definition at line 155 of file socket.hpp.

Function Documentation

◆ close()

auto io::socket::close ( native_socket_type socket ) -> int

inlinenoexcept

Closes a socket descriptor on POSIX systems.

Closes a socket descriptor on Windows systems.

This function wraps the native close function.

Parameters

socket The native socket handle to close.

Returns: 0 on success, or an error code on failure.

This function wraps the native ::closesocket function.

Parameters

socket The native socket handle to close.

Returns: 0 on success, or an error code on failure.

Definition at line 74 of file socket.hpp.

◆ fcntl()

template<typename... Args>

auto io::socket::fcntl	(	native_socket_type	socket,
		int	cmd,
		Args &&...	args
	)		-> int

inlinenoexcept

Provides a C++ wrapper for the POSIX fcntl function.

Provides a Windows compatibility implementation of the POSIX fcntl function.

This function is an inline wrapper around the standard POSIX fcntl system call. It forwards the provided arguments directly to the underlying fcntl function.

Parameters

socket	The native socket descriptor.
cmd	The `fcntl` command to execute.
...args	The arguments for the specified command.

Returns: The result of the underlying fcntl call. Typically, this is a value >= 0 on success and -1 on error, with errno set appropriately.

This function is a limited implementation of the POSIX fcntl function, specifically tailored for setting the non-blocking mode on a socket. It translates the fcntl(socket, F_SETFL, O_NONBLOCK) call to its Windows equivalent using ioctlsocket.

Note: This implementation only supports the F_SETFL command with the O_NONBLOCK flag. Any other usage will result in a compile-time or run-time assertion failure.

Parameters

socket	The native socket descriptor.
cmd	The `fcntl` command to execute. Only `F_SETFL` is supported.
...args	A single argument, which must be the flags to set. Only `O_NONBLOCK` is handled.

Returns: 0 on success, or SOCKET_ERROR on failure.

Definition at line 92 of file socket.hpp.

◆ recvmsg()

auto io::socket::recvmsg	(	native_socket_type	socket,
		socket_message_type *	msg,
		int	flags
	)		-> std::streamsize

inlinenoexcept

Receives a message from a socket.

Receives a message from a socket using WSARecvMsg.

This function wraps the native recvmsg function.

Parameters

socket	The native socket handle.
msg	A pointer to the `msghdr` structure to store the received message.
flags	A bitwise OR of flags to modify the receive behavior.

Returns: The number of bytes received on success, or SOCKET_ERROR on failure.

This function wraps the native ::WSARecvMsg function.

Parameters

socket	The native socket handle.
msg	A pointer to the `WSAMSG` structure to store the received message.
flags	A bitwise OR of flags to modify the receive behavior.

Returns: The number of bytes received on success, or a standard Windows Sockets error code on failure.

Definition at line 125 of file socket.hpp.

◆ sendmsg()

auto io::socket::sendmsg	(	native_socket_type	socket,
		const socket_message_type *	msg,
		int	flags
	)		-> std::streamsize

inlinenoexcept

Sends a message on a socket.

Sends a message on a socket using WSASendMsg.

This function wraps the native sendmsg function.

Parameters

socket	The native socket handle.
msg	A pointer to the `msghdr` structure containing the message to send.
flags	A bitwise OR of flags to modify the send behavior.

Returns: The number of bytes sent on success, or SOCKET_ERROR on failure.

This function wraps the native ::WSASendMsg function.

Parameters

socket	The native socket handle.
msg	A pointer to the `WSAMSG` structure containing the message to send.
flags	This parameter is ignored on Windows.

Returns: The number of bytes sent on success, or a standard Windows Sockets error code on failure.

Definition at line 109 of file socket.hpp.

◆ swap() [1/2]

auto io::socket::swap	(	socket_handle &	lhs,
		socket_handle &	rhs
	)		-> void

noexcept

This operation is thread-safe.

Parameters

lhs	The first `socket_handle`.
rhs	The second `socket_handle`.

Definition at line 67 of file socket_handle.cpp.

◆ swap() [2/2]

auto io::socket::swap	(	socket_message &	lhs,
		socket_message &	rhs
	)		-> void

noexcept

This function atomically swaps the contents of two socket_message instances using a dual-mutex lock to prevent deadlocks.

Parameters

lhs	The first `socket_message` instance.
rhs	The second `socket_message` instance.

Note: This function uses std::scoped_lock to prevent deadlocks when locking multiple mutexes.

Definition at line 33 of file socket_message.cpp.

◆ tag_invoke() [1/16]

auto io::socket::tag_invoke	(	accept_t	,
		const socket_handle &	socket,
		sockaddr_type *	addr,
		socklen_type *	len
	)		-> native_socket_type

Accepts an incoming connection on a listening socket.

This function extracts the first connection request from the queue of pending connections for a listening socket.

Parameters

socket	The listening socket handle.
addr	A pointer to a `sockaddr_type` structure that will be filled with the address of the connecting socket.
len	A pointer to a `socklen_type` that will be filled with the length of the address.

Returns: The native socket handle for the accepted socket, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle, socket_address

Definition at line 47 of file socket.cpp.

◆ tag_invoke() [2/16]

auto io::socket::tag_invoke	(	accept_t	,
		const socket_handle &	socket,
		socket_address	addr = `{}`
	)		-> std::tuple< socket_handle, socket_address >

Accepts an incoming connection on a listening socket.

This function extracts the first connection request from the queue of pending connections for a listening socket.

Parameters

socket	The listening socket handle.
addr	An optional `socket_address` to be populated with the address of the connecting socket.

Returns: A std::tuple containing a socket_handle for the accepted socket and a socket_address for the connecting socket.

Exceptions

std::system_error on failure.

See also: socket_handle, socket_address

Definition at line 52 of file socket.cpp.

◆ tag_invoke() [3/16]

auto io::socket::tag_invoke	(	bind_t	,
		const socket_handle &	socket,
		const sockaddr_type *	addr,
		socklen_type	len
	)		-> int

Binds a socket to a local address.

This function associates a socket with a specific local address. This is necessary before a socket can accept incoming connections.

Parameters

socket	The socket handle to bind.
addr	A pointer to a `sockaddr_type` structure containing the address to bind to.
len	The length of the `addr` structure.

Returns: 0 on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle, socket_address

Definition at line 20 of file socket.cpp.

◆ tag_invoke() [4/16]

auto io::socket::tag_invoke	(	bind_t	,
		const socket_handle &	socket,
		const socket_address &	addr
	)		-> int

Binds a socket to a local address.

This function associates a socket with a specific local address. This is necessary before a socket can accept incoming connections.

Parameters

socket	The socket handle to bind.
addr	The `socket_address` to bind to.

Returns: 0 on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle, socket_address

Definition at line 25 of file socket.cpp.

◆ tag_invoke() [5/16]

auto io::socket::tag_invoke	(	connect_t	,
		const socket_handle &	socket,
		const sockaddr_type *	addr,
		socklen_type	len
	)		-> int

Connects a socket to a remote address.

This function establishes a connection to a specified remote address.

Parameters

socket	The socket handle to connect.
addr	A pointer to a `sockaddr_type` structure containing the remote address to connect to.
len	The length of the `addr` structure.

Returns: 0 on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle, socket_address

Definition at line 36 of file socket.cpp.

◆ tag_invoke() [6/16]

auto io::socket::tag_invoke	(	connect_t	,
		const socket_handle &	socket,
		const socket_address &	addr
	)		-> int

Connects a socket to a remote address.

This function establishes a connection to a specified remote address.

Parameters

socket	The socket handle to connect.
addr	The `socket_address` to connect to.

Returns: 0 on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle, socket_address

Definition at line 41 of file socket.cpp.

◆ tag_invoke() [7/16]

template<typename... Args>

auto io::socket::tag_invoke	(	fcntl_t	tag,
		const socket_handle &	socket,
		int	cmd,
		Args &&...	args
	)		-> int

Performs a file control operation on a socket.

Parameters

socket	The socket to perform the operation on.
cmd	The file control command to execute.
args	Additional arguments for the command.

Returns: The result of the operation, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle

Definition at line 277 of file socket.hpp.

◆ tag_invoke() [8/16]

auto io::socket::tag_invoke	(	getpeername_t	,
		const socket_handle &	socket,
		sockaddr_type *	addr,
		socklen_type *	len
	)		-> int

Gets the peer address of a connected socket.

Parameters

socket	The socket to get the peer address from.
addr	A pointer to a `sockaddr` structure to store the peer address.
len	A pointer to a `socklen_t` to store the length of the address.

Returns: 0 on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle, socket_address

Definition at line 109 of file socket.cpp.

◆ tag_invoke() [9/16]

auto io::socket::tag_invoke	(	getsockname_t	,
		const socket_handle &	socket,
		sockaddr_type *	addr,
		socklen_type *	len
	)		-> int

Gets the local address of a socket.

Parameters

socket	The socket to get the local address from.
addr	A pointer to a `sockaddr` structure to store the local address.
len	A pointer to a `socklen_t` to store the length of the address.

Returns: 0 on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle, socket_address

Definition at line 104 of file socket.cpp.

◆ tag_invoke() [10/16]

auto io::socket::tag_invoke	(	getsockopt_t	,
		const socket_handle &	socket,
		int	level,
		int	optname,
		void *	optval,
		socklen_type *	optlen
	)		-> int

Gets a socket option.

Parameters

socket	The socket to get the option from.
level	The protocol level at which the option resides.
optname	The name of the option.
optval	A pointer to the buffer where the option value will be stored.
optlen	A pointer to the length of the buffer.

Returns: 0 on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle

Definition at line 90 of file socket.cpp.

◆ tag_invoke() [11/16]

auto io::socket::tag_invoke	(	listen_t	,
		const socket_handle &	socket,
		int	backlog
	)		-> int

Sets a socket to listen for incoming connections.

This function marks a socket as a passive socket, which will be used to accept incoming connection requests.

Parameters

socket	The socket handle to set to listen.
backlog	The maximum number of pending connections that can be queued.

Returns: 0 on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle

Definition at line 31 of file socket.cpp.

◆ tag_invoke() [12/16]

auto io::socket::tag_invoke	(	recvmsg_t	,
		const socket_handle &	socket,
		socket_message_type *	msg,
		int	flags
	)		-> std::streamsize

Receives a message from a socket.

Parameters

socket	The socket to receive the message from.
msg	A pointer to a `msghdr` structure to store the received message.
flags	A bitmask of flags to control the receive operation.

Returns: The number of bytes received on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle, socket_message

Definition at line 84 of file socket.cpp.

◆ tag_invoke() [13/16]

auto io::socket::tag_invoke	(	sendmsg_t	,
		const socket_handle &	socket,
		const socket_message &	msg
	)		-> std::streamsize

Sends a message on a socket using a socket_message object.

This overload sends a message encapsulated in a socket_message, which provides a thread-safe container for scatter-gather I/O, ancillary data, and other message properties.

Parameters

socket	The socket to send the message on.
msg	The `socket_message` to send.

Returns: The number of bytes sent on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle, socket_message

Definition at line 67 of file socket.cpp.

◆ tag_invoke() [14/16]

auto io::socket::tag_invoke	(	sendmsg_t	,
		const socket_handle &	socket,
		const socket_message_type *	msg,
		int	flags
	)		-> std::streamsize

Sends a message on a socket.

Parameters

socket	The socket to send the message on.
msg	A pointer to a `msghdr` structure containing the message to send.
flags	A bitmask of flags to control the send operation.

Returns: The number of bytes sent on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle, socket_message

Definition at line 60 of file socket.cpp.

◆ tag_invoke() [15/16]

auto io::socket::tag_invoke	(	setsockopt_t	,
		const socket_handle &	socket,
		int	level,
		int	optname,
		const void *	optval,
		socklen_type	optlen
	)		-> int

Sets a socket option.

Parameters

socket	The socket to set the option on.
level	The protocol level at which the option resides.
optname	The name of the option.
optval	A pointer to the buffer containing the option value.
optlen	The length of the buffer.

Returns: 0 on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle

Definition at line 97 of file socket.cpp.

◆ tag_invoke() [16/16]

auto io::socket::tag_invoke	(	shutdown_t	,
		const socket_handle &	socket,
		int	how
	)		-> int

Shuts down a socket connection.

This function disables sending, receiving, or both on a socket.

Parameters

socket	The socket to shut down.
how	An integer indicating how to shut down the connection (e.g., SHUT_RD, SHUT_WR, SHUT_RDWR).

Returns: 0 on success, or -1 on error. In case of an error, errno is set to indicate the error.

See also: socket_handle

Definition at line 114 of file socket.cpp.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ancillary_buffer

◆ native_socket_type

◆ scatter_gather_buffer

◆ sockaddr_storage_type

◆ sockaddr_type

◆ socket_buffer_type

◆ socket_message_type

◆ socklen_type

Function Documentation

◆ close()

◆ fcntl()

◆ recvmsg()

◆ sendmsg()

◆ swap() [1/2]

◆ swap() [2/2]

◆ tag_invoke() [1/16]

◆ tag_invoke() [2/16]

◆ tag_invoke() [3/16]

◆ tag_invoke() [4/16]

◆ tag_invoke() [5/16]

◆ tag_invoke() [6/16]

◆ tag_invoke() [7/16]

◆ tag_invoke() [8/16]

◆ tag_invoke() [9/16]

◆ tag_invoke() [10/16]

◆ tag_invoke() [11/16]

◆ tag_invoke() [12/16]

◆ tag_invoke() [13/16]

◆ tag_invoke() [14/16]

◆ tag_invoke() [15/16]

◆ tag_invoke() [16/16]