Generic socket level option setter/getter helper. More...

#include <SocketOptions.hxx>

Inheritance diagram for cosmos::SocketOptions:

Classes
struct	Linger
	Special option struct for getLinger() and setLinger(). More...

Public Member Functions
bool	acceptsConnections () const
	Returns whether the socket is currently in a listening state, accepting connections.

void	bindToDevice (const SysString ifname)
	Bind the socket to a specific network device.

std::string	boundDevice () const
	Returns the name of the network device this socket is bound to, if any.

void	unbindDevice ()
	Removes a previously established binding to a network device.

void	enableDebug (const bool on_off)
	Enable socket debugging.

SocketFamily	family () const
	Returns the family of the current socket.

SocketType	type () const
	Returns the type of the current socket.

SocketProtocol	protocol () const
	Returns the protocol of the current socket.

Errno	lastError ()
	Returns and clears the result of a non-blocking connection attempt.

void	setReuseAddress (const bool on_off)
	Allow or disallow reuse of local addresses.

void	setReusePort (const bool on_off)
	Allow parallel use of the same port.

void	setKeepalive (const bool on_off)
	Enables the sending of keepalive messages for connection oriented sockets.

void	setMark (const uint32_t mark)
	Sets a mark for this socket.

Linger	getLinger () const
	Gets the current linger setting for this socket.

void	setLinger (const Linger &linger)
	Sets the current linger setting for this socket.

void	setZeroCopy (const bool on_off)
	Signals the intent to use MessageFlag::ZEROCOPY in socket I/O.

void	setReceiveLowerBound (const int bytes)
	Sets the minimum size of input bytes to pass on to userspace.

Protected Member Functions
	SocketOptions (FileDescriptor fd)

Protected Member Functions inherited from cosmos::SockOptBase< OptLevel::SOCKET >
	SockOptBase (FileDescriptor fd)
	Perform socket options on the given file descriptor.

	SockOptBase (const SockOptBase &)=delete

bool	getBoolOption (const OptName name) const
	Return a boolean style option.

void	setBoolOption (const OptName name, const bool val)
	Set a boolean style option.

int	getIntOption (const OptName name) const
	Return an integer option.

void	setIntOption (const OptName name, const int val)
	Set an integer option.

std::string	getStringOption (const OptName name, size_t max_len) const
	Return a null terminated string option.

void	setStringOption (const OptName name, const SysString str)
	Set a null terminated string option.

std::string	getPeerSec () const
	Returns the labeled IPSEC or NetLabel of the peer.

SockOptBase &	operator= (const SockOptBase &)=delete

Friends
class	Socket

Additional Inherited Members
Protected Attributes inherited from cosmos::SockOptBase< OptLevel::SOCKET >
FileDescriptor	m_sock
	The socket file descriptor to operate on.

Static Protected Attributes inherited from cosmos::SockOptBase< OptLevel::SOCKET >
static constexpr OptLevel	M_LEVEL
	The option level to operate on.

Detailed Description

Generic socket level option setter/getter helper.

This helper type offers generic socket level options that are available for all types of sockets.

This type cannot be freely created, but can only be obtained via Socket::sockOptions().

The getting of options that don't change the socket's internal state is allowed on const instances of SocketOptions.

Definition at line 26 of file SocketOptions.hxx.

Constructor & Destructor Documentation

◆ SocketOptions()

cosmos::SocketOptions::SocketOptions ( FileDescriptor fd )

inlineexplicitprotected

Definition at line 232 of file SocketOptions.hxx.

232: SockOptBase{fd} {}

cosmos::SockOptBase< OptLevel::SOCKET >::SockOptBase

SockOptBase(FileDescriptor fd)

Definition SockOptBase.hxx:22

Member Function Documentation

◆ acceptsConnections()

bool cosmos::SocketOptions::acceptsConnections ( ) const

inline

Returns whether the socket is currently in a listening state, accepting connections.

Definition at line 71 of file SocketOptions.hxx.

                                        {
                return getBoolOption(OptName{SO_ACCEPTCONN});
        }

◆ bindToDevice()

void cosmos::SocketOptions::bindToDevice ( const SysString ifname )

Bind the socket to a specific network device.

When a socket is bound to a network device then only packets seen on this network device will be processed by the socket.

This option only works for some socket types, notably IP based sockets. It does not work for packet sockets.

Definition at line 9 of file SocketOptions.cxx.

                                                       {
        setStringOption(OptName{SO_BINDTODEVICE}, ifname);
}

◆ boundDevice()

std::string cosmos::SocketOptions::boundDevice ( ) const

Returns the name of the network device this socket is bound to, if any.

Definition at line 13 of file SocketOptions.cxx.

                                           {
        return getStringOption(OptName{SO_BINDTODEVICE}, MAX_NET_INTERFACE_NAME);
}

◆ enableDebug()

void cosmos::SocketOptions::enableDebug ( const bool on_off )

inline

Enable socket debugging.

Enabling this requires the CAP_NET_ADMIN capability. It seems this is mostly used for TCP sockets. The kernel will then keep additional debugging information about the connection and tools like trpt can read out this information for debugging purposes.

Definition at line 100 of file SocketOptions.hxx.

                                            {
                setBoolOption(OptName{SO_DEBUG}, on_off);
        }

◆ family()

SocketFamily cosmos::SocketOptions::family ( ) const

inline

Returns the family of the current socket.

Definition at line 105 of file SocketOptions.hxx.

                                    {
                const auto family = getIntOption(OptName{SO_DOMAIN});
                return SocketFamily{family};
        }

◆ getLinger()

SocketOptions::Linger cosmos::SocketOptions::getLinger ( ) const

Gets the current linger setting for this socket.

See also: setLinger()

Definition at line 24 of file SocketOptions.cxx.

                                                   {
        Linger ret;
        auto len = getsockopt(m_sock, M_LEVEL, OptName{SO_LINGER}, &ret, sizeof(ret));
 
        if (len != sizeof(ret)) {
                cosmos_throw (RuntimeError("getsockopt: short read on SO_LINGER"));
        }
 
        return ret;
}

◆ lastError()

Errno cosmos::SocketOptions::lastError ( )

inline

Returns and clears the result of a non-blocking connection attempt.

This error code is specially used for the connect() system call on non-blocking sockets. Once the connection result is here, the socket will be marked as writable for select(). The actual result can be retrieved via this error code here. It will be Errno::NO_ERROR on success, or one of the documented error codes for connect() on error.

Fetching this error code also clears it in the kernel. For this reason this getter is not const, since it modifies the socket's state.

Definition at line 135 of file SocketOptions.hxx.

                          {
                const auto error = getIntOption(OptName{SO_ERROR});
                return Errno{error};
        }

◆ protocol()

SocketProtocol cosmos::SocketOptions::protocol ( ) const

inline

Returns the protocol of the current socket.

Definition at line 117 of file SocketOptions.hxx.

                                        {
                const auto protocol = getIntOption(OptName{SO_PROTOCOL});
                return SocketProtocol{protocol};
        }

◆ setKeepalive()

void cosmos::SocketOptions::setKeepalive ( const bool on_off )

inline

Enables the sending of keepalive messages for connection oriented sockets.

The details of the keepalive algorithm are socket dependent. For TCP sockets TCP specific options can be set on top of this to control the algorithm in detail, see TCPOptions.

Definition at line 179 of file SocketOptions.hxx.

                                             {
                setBoolOption(OptName{SO_KEEPALIVE}, on_off);
        }

◆ setLinger()

void cosmos::SocketOptions::setLinger ( const Linger & linger )

Sets the current linger setting for this socket.

This controls the behaviour close() and shutdown() calls on the socket. If enabled then these system calls will block for at most the given time in seconds for any remaining queued messages to be sent out over the socket.

If disabled then lingering happens in the background. When a process exits without explicitly closing the socket then lingering is always done in the background.

Definition at line 35 of file SocketOptions.cxx.

                                                  {
        setsockopt(m_sock, M_LEVEL, OptName{SO_LINGER}, &linger, sizeof(linger));
}

◆ setMark()

void cosmos::SocketOptions::setMark ( const uint32_t mark )

Sets a mark for this socket.

The mark value can be used for socket based routing e.g. iptables can add rules for packets carrying a specific mark. Setting this requires the CAP_NET_ADMIN capability.

Definition at line 17 of file SocketOptions.cxx.

                                               {
        // this being an uint32_t is not properly documented in the man page
        // but can be found in the `struct sock` structure in the kernel
        // sources.
        setsockopt<uint32_t>(m_sock, M_LEVEL, OptName{SO_MARK}, mark);
}

◆ setReceiveLowerBound()

void cosmos::SocketOptions::setReceiveLowerBound ( const int bytes )

inline

Sets the minimum size of input bytes to pass on to userspace.

Settings this option causes all input operations on the socket to block until at least bytes many bytes are available. This also affects select() and poll() APIs.

Definition at line 224 of file SocketOptions.hxx.

                                                   {
                setIntOption(OptName{SO_RCVLOWAT}, bytes);
        }

◆ setReuseAddress()

void cosmos::SocketOptions::setReuseAddress ( const bool on_off )

inline

Allow or disallow reuse of local addresses.

For IP level sockets this means that the socket may bind to a local address except if there is an active listening socket already bound to the address.

Especially for TCP sockets it may otherwise not be possible to bind to a local address that has recently been in use by another process, because strict rules prevent that packets that belong to an old connection end up in a new connection.

Definition at line 151 of file SocketOptions.hxx.

                                                {
                setBoolOption(OptName{SO_REUSEADDR}, on_off);
        }

◆ setReusePort()

void cosmos::SocketOptions::setReusePort ( const bool on_off )

inline

Allow parallel use of the same port.

For IP based sockets setting this option allows the same local address and port to be bound multiple times. The purpose for this is mainly improved performance e.g. multiple threads can have their own socket for accept() resulting in a better balancing than other approaches. With UDP sockets the load balancing of datagram reception can be performed via individual sockets.

For this to work all sockets that share the local address and port need to set this option and they also need to share the same effective UID (to prevent socket hijacking between different local users).

Definition at line 169 of file SocketOptions.hxx.

                                             {
                setBoolOption(OptName{SO_REUSEPORT}, on_off);
        }

◆ setZeroCopy()

void cosmos::SocketOptions::setZeroCopy ( const bool on_off )

inline

Signals the intent to use MessageFlag::ZEROCOPY in socket I/O.

See also: MessageFlag::ZEROCOPY

Definition at line 214 of file SocketOptions.hxx.

                                            {
                setBoolOption(OptName{SO_ZEROCOPY}, on_off);
        }

◆ type()

SocketType cosmos::SocketOptions::type ( ) const

inline

Returns the type of the current socket.

Definition at line 111 of file SocketOptions.hxx.

                                {
                const auto type = getIntOption(OptName{SO_TYPE});
                return SocketType{type};
        }

◆ unbindDevice()

void cosmos::SocketOptions::unbindDevice ( )

inline

Removes a previously established binding to a network device.

Definition at line 89 of file SocketOptions.hxx.

                            {
                bindToDevice("");
        }

Friends And Related Symbol Documentation

◆ Socket

friend class Socket

friend

Definition at line 230 of file SocketOptions.hxx.

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

include/net/SocketOptions.hxx
src/net/SocketOptions.cxx

Classes

Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SocketOptions()

Member Function Documentation

◆ acceptsConnections()

◆ bindToDevice()

◆ boundDevice()

◆ enableDebug()

◆ family()

◆ getLinger()

◆ lastError()

◆ protocol()

◆ setKeepalive()

◆ setLinger()

◆ setMark()

◆ setReceiveLowerBound()

◆ setReuseAddress()

◆ setReusePort()

◆ setZeroCopy()

◆ type()

◆ unbindDevice()

Friends And Related Symbol Documentation

◆ Socket