jsocketpp::UnixSocket Class Reference

Cross-platform abstraction for Unix domain sockets. More...

#include <UnixSocket.hpp>

Inheritance diagram for jsocketpp::UnixSocket:

Collaboration diagram for jsocketpp::UnixSocket:

Public Member Functions
	UnixSocket (std::string_view path, std::size_t bufferSize=512)
	Constructs a UnixSocket and connects or binds to the specified path.
	UnixSocket (const UnixSocket &)=delete
	Copy constructor deleted to prevent copying.
UnixSocket &	operator= (const UnixSocket &)=delete
	Copy assignment operator deleted to prevent copying.
	UnixSocket (UnixSocket &&rhs) noexcept
	Move constructor transfers ownership of socket resources.
UnixSocket &	operator= (UnixSocket &&rhs) noexcept
	Move assignment operator transfers ownership of socket resources.
	~UnixSocket () noexcept override
	Destructor.
void	bind ()
	Binds the socket.
void	listen (int backlog=SOMAXCONN) const
	Marks the socket as a passive socket to accept incoming connections.
UnixSocket	accept () const
	Accepts an incoming connection.
void	connect ()
	Connects the socket.
size_t	write (std::string_view data) const
	Writes data to the socket.
size_t	read (char *buffer, std::size_t len) const
	Reads data from the socket into a buffer.
template<typename T>
T	read ()
	Reads a trivially copyable type from the socket.
void	close ()
	Closes the socket.
bool	isValid () const
	Checks if the socket is valid (open).
std::string	getSocketPath () const
	Returns the path of the Unix domain socket.
void	setNonBlocking (bool nonBlocking) const
	Sets the socket to non-blocking or blocking mode.
void	setTimeout (int millis) const
	Sets a timeout for socket operations.
template<>
std::string	read ()
	Template specialization to read a string from the Unix domain socket.

Static Public Member Functions
static bool	isPathInUse (std::string_view path)
	Checks whether a UNIX domain socket path is currently in use (i.e., a process is listening on it).

Protected Member Functions
	UnixSocket ()
	Default constructor for internal use (e.g., accept()).

Private Attributes
bool	_isListening = false
	True if the socket is listening for connections.
std::string	_socketPath {}
	Path for the Unix domain socket.
SOCKADDR_UN	_addr {}
	Address structure for Unix domain sockets.
std::vector< char >	_internalBuffer
	Internal buffer for read operations.

Additional Inherited Members
Private Member Functions inherited from jsocketpp::SocketOptions
	SocketOptions ()=delete
	Default constructor (deleted) for SocketOptions base class.
	SocketOptions (const SOCKET sock) noexcept
	Initializes the socket option interface with a specific socket descriptor.
virtual	~SocketOptions ()=default
	Virtual destructor for safe polymorphic destruction.
	SocketOptions (const SocketOptions &)=delete
	Copy constructor (deleted) for SocketOptions.
	SocketOptions (SocketOptions &&) noexcept=default
	Move constructor for SocketOptions.
SocketOptions &	operator= (const SocketOptions &)=delete
	Copy assignment operator (deleted) for SocketOptions.
SocketOptions &	operator= (SocketOptions &&) noexcept=default
	Move assignment operator for SocketOptions.
SOCKET	getSocketFd () const noexcept
	Retrieves the native socket handle (file descriptor or OS-level handle).
void	setOption (int level, int optName, int value)
	Sets a low-level socket option on the underlying socket.
void	setOption (int level, int optName, const void *value, socklen_t len)
	Sets a low-level socket option using a structured or binary value.
int	getOption (int level, int optName) const
	Retrieves the current value of a low-level socket option.
void	getOption (int level, int optName, void *result, socklen_t *len) const
	Retrieves a socket option into a structured or binary buffer.
void	setReuseAddress (bool on)
	Enables or disables the SO_REUSEADDR socket option.
bool	getReuseAddress () const
	Queries whether the socket is currently configured to allow address reuse.
void	setReceiveBufferSize (std::size_t size)
	Sets the socket's receive buffer size (SO_RCVBUF).
int	getReceiveBufferSize () const
	Retrieves the current receive buffer size (SO_RCVBUF) of the socket.
void	setSendBufferSize (std::size_t size)
	Sets the socket's send buffer size (SO_SNDBUF).
int	getSendBufferSize () const
	Retrieves the current send buffer size (SO_SNDBUF) of the socket.
void	setSoLinger (bool enable, int seconds)
	Configures the socket's linger behavior (SO_LINGER) during close.
std::pair< bool, int >	getSoLinger () const
	Retrieves the current SO_LINGER configuration of the socket.
void	setKeepAlive (bool on)
	Enables or disables TCP-level keepalive behavior on the socket (SO_KEEPALIVE).
bool	getKeepAlive () const
	Checks whether TCP-level keepalive (SO_KEEPALIVE) is currently enabled.
void	setSoRecvTimeout (int millis)
	Sets the socket receive timeout (SO_RCVTIMEO) in milliseconds.
void	setSoSendTimeout (int millis)
	Sets the socket send timeout (SO_SNDTIMEO) in milliseconds.
int	getSoRecvTimeout () const
	Retrieves the socket receive timeout (SO_RCVTIMEO) in milliseconds.
int	getSoSendTimeout () const
	Retrieves the socket send timeout (SO_SNDTIMEO) in milliseconds.
void	setNonBlocking (bool nonBlocking)
	Enables or disables non-blocking mode on the socket.
bool	getNonBlocking () const
	Queries whether the socket is currently in non-blocking mode.
void	setTcpNoDelay (bool on)
	Enables or disables Nagle’s algorithm (TCP_NODELAY) on TCP sockets.
bool	getTcpNoDelay () const
	Queries whether Nagle's algorithm (TCP_NODELAY) is currently disabled.
void	setBroadcast (bool on)
	Enables or disables the ability to send UDP broadcast messages.
bool	getBroadcast () const
	Checks whether the socket is currently allowed to send broadcast messages.
void	setIPv6Only (bool enable)
	Enables or disables IPV6_V6ONLY mode for IPv6-capable sockets.
bool	getIPv6Only () const
	Queries whether the IPV6_V6ONLY option is enabled on this socket.
void	setReusePort (const bool enable)
	Enables or disables the SO_REUSEPORT socket option.
bool	getReusePort () const
	Checks whether the SO_REUSEPORT option is currently enabled on the socket.
void	setMulticastTTL (int ttl)
	Set the default multicast hop limit / TTL for this socket.
int	getMulticastTTL () const
	Get the socket’s default multicast hop limit / TTL.
void	setMulticastLoopback (bool enable)
	Enable or disable multicast loopback for this socket.
bool	getMulticastLoopback () const
	Read the socket’s multicast loopback flag.
void	setMulticastInterfaceIPv4 (in_addr addr)
	Select the outgoing IPv4 interface for multicast.
void	setMulticastInterfaceIPv6 (unsigned int ifindex)
	Select the outgoing IPv6 interface for multicast.
void	joinGroupIPv4 (in_addr group, in_addr iface)
	Join an IPv4 any-source multicast (ASM) group on a specific interface.
void	leaveGroupIPv4 (in_addr group, in_addr iface)
	Leave a previously joined IPv4 multicast group on a specific interface.
void	joinGroupIPv6 (in6_addr group, unsigned int ifindex)
	Join an IPv6 any-source multicast (ASM) group on a specific interface index.
void	leaveGroupIPv6 (in6_addr group, unsigned int ifindex)
	Leave a previously joined IPv6 multicast group on a specific interface index.
void	setSocketFd (const SOCKET sock) noexcept
	Updates the socket descriptor used by this object.
virtual bool	isPassiveSocket () const noexcept
	Indicates whether the socket behaves as a passive (listening) socket.
Static Private Member Functions inherited from jsocketpp::SocketOptions
static bool	is_ipv4_multicast (const in_addr v4)
	Test whether an IPv4 address is in the multicast range (224.0.0.0/4).
static bool	is_ipv6_multicast (const in6_addr &v6)
	Test whether an IPv6 address is in the multicast range (ff00::/8).
static int	detectFamily (SOCKET fd)
	Determine the address family (AF_INET or AF_INET6) of a socket.

Detailed Description

Cross-platform abstraction for Unix domain sockets.

The UnixSocket class provides a convenient, modern C++20-style interface for using Unix domain sockets, also known as AF_UNIX sockets. Unix sockets are used for fast inter-process communication (IPC) on the same host, and use a file path on the local file system for addressing.

On POSIX platforms (Linux, macOS), AF_UNIX sockets are widely supported. On Windows, support is available in Windows 10 (1803+, build 17134) and newer.

Main Features

• Bind: Create and bind a socket to a filesystem path for listening/accepting connections.
• Listen/Accept: Wait for incoming connections and accept them (server-side).
• Connect: Connect to a Unix domain socket path (client-side).
• Read/Write: Send and receive data over the connection, supporting both binary and string types.
• Non-blocking & Timeout: Support for non-blocking I/O and operation timeouts.
• Automatic cleanup: Unlinks the socket file on destruction.

Note

Not thread-safe. Each UnixSocket should only be used from one thread at a time.

On Windows, AF_UNIX is supported on Windows 10 1803 and later only. On unsupported platforms, attempting to use this class will result in a compilation error.

Example: Simple Echo Server

#include <jsocketpp/UnixSocket.hpp>
using namespace jsocketpp;
 
int main() {
    UnixSocket server("/tmp/echo.sock");
    server.bind();
    server.listen();
 
    while (true) {
        UnixSocket client = server.accept();
        std::string data = client.read<std::string>();
        client.write(data); // Echo back
    }
}

Example: Simple Client

#include <jsocketpp/UnixSocket.hpp>
using namespace jsocketpp;
 
int main() {
    UnixSocket sock("/tmp/echo.sock");
    sock.connect();
    sock.write("Hello, Unix domain socket!");
    std::string response = sock.read<std::string>();
}

Limitations

• Not suitable for remote (network) connections; only for IPC on the same host.
• The socket file is automatically deleted on destruction.

Constructor & Destructor Documentation

UnixSocket() [1/4]

UnixSocket::UnixSocket ( std::string_view path, std::size_t bufferSize = 512 )

explicit

Constructs a UnixSocket and connects or binds to the specified path.

Parameters

path	The filesystem path for the Unix domain socket.
bufferSize	Size of the internal read buffer (default: 512).

UnixSocket() [2/4]

jsocketpp::UnixSocket::UnixSocket ( const UnixSocket & )

delete

Copy constructor deleted to prevent copying.

UnixSocket() [3/4]

UnixSocket::UnixSocket ( UnixSocket && rhs )

noexcept

Move constructor transfers ownership of socket resources.

Parameters

rhs	The UnixSocket to move from.

~UnixSocket()

UnixSocket::~UnixSocket ( )

overridenoexcept

Destructor.

Closes the socket if it is open.

UnixSocket() [4/4]

jsocketpp::UnixSocket::UnixSocket ( )

inlineprotected

Default constructor for internal use (e.g., accept()).

Member Function Documentation

accept()

UnixSocket UnixSocket::accept ( ) const

nodiscard

Accepts an incoming connection.

Returns

A new UnixSocket representing the accepted connection.

Exceptions

std::socket_exception

if accept fails.

bind()

void UnixSocket::bind

(

)

Binds the socket.

Exceptions

std::socket_exception

if binding fails.

close()

void UnixSocket::close

(

)

Closes the socket.

connect()

void UnixSocket::connect

(

)

Connects the socket.

Exceptions

std::socket_exception

if connection fails.

getSocketPath()

std::string jsocketpp::UnixSocket::getSocketPath ( ) const

inlinenodiscard

Returns the path of the Unix domain socket.

Returns

String containing the filesystem path of the socket.

isPathInUse()

bool UnixSocket::isPathInUse ( std::string_view path )

static

Checks whether a UNIX domain socket path is currently in use (i.e., a process is listening on it).

This function attempts to connect to the given UNIX socket path. If the connection succeeds, the path is in use. If the connection fails with ECONNREFUSED or ENOENT, the path is not in use (either no process is listening, or the file does not exist).

Parameters

path	The UNIX socket file system path to check.

Returns

true if a process is listening on the socket at the given path, false otherwise.

isValid()

bool jsocketpp::UnixSocket::isValid ( ) const

inlinenodiscard

Checks if the socket is valid (open).

Returns

true if the socket is valid, false otherwise.

listen()

void UnixSocket::listen

(

int

backlog = SOMAXCONN

)

const

Marks the socket as a passive socket to accept incoming connections.

Parameters

backlog

The maximum length to which the queue of pending connections may grow.

Exceptions

std::socket_exception

if listen fails.

The backlog parameter defines the maximum number of pending connections that can be queued up before connections are refused.

operator=() [1/2]

UnixSocket & jsocketpp::UnixSocket::operator= ( const UnixSocket & )

delete

Copy assignment operator deleted to prevent copying.

operator=() [2/2]

UnixSocket & UnixSocket::operator= ( UnixSocket && rhs )

noexcept

Move assignment operator transfers ownership of socket resources.

Parameters

rhs	The UnixSocket to move from.

Returns

Reference to this UnixSocket.

read() [1/3]

template<>

std::string jsocketpp::UnixSocket::read ( )

inline

Template specialization to read a string from the Unix domain socket.

Reads data from the socket into the internal buffer and returns it as a string. Uses the socket's internal buffer size (set via constructor) as the maximum read length. The actual returned string length may be shorter depending on how much data was received.

Returns

String containing the received data.

Exceptions

SocketException

If a socket error occurs or the connection is closed by the remote peer.

See also

UnixSocket() To modify the maximum read length via bufferSize parameter.

read() [2/3]

template<typename T>

T jsocketpp::UnixSocket::read ( )

inline

Reads a trivially copyable type from the socket.

Template Parameters

T	Type to read (must be trivially copyable).

Returns

Value of type T read from the socket.

Exceptions

SocketException

on error or disconnect.

read() [3/3]

size_t UnixSocket::read	(	char *	buffer,
		std::size_t	len ) const

Reads data from the socket into a buffer.

Parameters

buffer	Pointer to the buffer to read data into.
len	Maximum number of bytes to read.

Returns

The number of bytes read.

Exceptions

std::socket_exception

if reading fails.

setNonBlocking()

void UnixSocket::setNonBlocking

(

bool

nonBlocking

)

const

Sets the socket to non-blocking or blocking mode.

This function configures the socket to operate in either non-blocking or blocking mode, depending on the value of the nonBlocking parameter. In non-blocking mode, socket operations will return immediately if they cannot be completed, rather than blocking the calling thread.

Parameters

nonBlocking

If true, sets the socket to non-blocking mode; if false, sets it to blocking mode.

setTimeout()

void UnixSocket::setTimeout

(

int

millis

)

const

Sets a timeout for socket operations.

Parameters

millis

Timeout in milliseconds.

write()

size_t UnixSocket::write ( std::string_view data ) const

nodiscard

Writes data to the socket.

Parameters

data	The data to write.

Returns

The number of bytes written.

Exceptions

std::socket_exception

if writing fails.

Member Data Documentation

_addr

SOCKADDR_UN jsocketpp::UnixSocket::_addr {}

private

Address structure for Unix domain sockets.

_internalBuffer

std::vector<char> jsocketpp::UnixSocket::_internalBuffer

private

Internal buffer for read operations.

_isListening

bool jsocketpp::UnixSocket::_isListening = false

private

True if the socket is listening for connections.

_socketPath

std::string jsocketpp::UnixSocket::_socketPath {}

private

Path for the Unix domain socket.

---

The documentation for this class was generated from the following files:

• include/jsocketpp/UnixSocket.hpp
• src/UnixSocket.cpp