Address type for local UNIX domain sockets. More...

#include <UnixAddress.hxx>

Inheritance diagram for cosmos::UnixAddress:

Public Types
using	Abstract = NamedBool<struct abstract_address_t, false>
	Strong boolean type to indicate the use an abstract address.

Public Member Functions
	UnixAddress ()
	Creates an empty address.

	UnixAddress (const std::string_view path, const Abstract abstract=Abstract{false})
	Creates an address from the given path which can also be abstract.

SocketFamily	family () const override
	Returns the concrete SocketFamily for the implementation address type.

size_t	size () const override
	Returns the size of the structure considering the currently set path length only.

size_t	maxSize () const override
	Returns the maximum address size without taking into account the currently set path.

size_t	maxPathLen () const
	Maximum path length that can be stored in a UnixAddress structure.

void	setPath (const std::string_view path, const Abstract abstract=Abstract{false})
	Sets a new path for the address.

std::string_view	getPath () const
	Returns the currently set path.

std::string	label () const
	Returns a human readable label for the contained path.

bool	isAbstract () const
	Returns whether currently an abstract path is contained.

bool	isUnnamed () const
	Returns whether this address is currently unnamed (empty).

bool	operator== (const UnixAddress &other) const

bool	operator!= (const UnixAddress &other) const

Public Member Functions inherited from cosmos::SocketAddress

Protected Member Functions
void	update (size_t new_length) override
	Update the address structure after it has been filled in by the kernel.

sockaddr *	basePtr () override
	Returns a mutable pointer to the `sockaddr*` base structure.

const sockaddr *	basePtr () const override
	Returns a const pointer to the `sockaddr*` base structure.

Protected Member Functions inherited from cosmos::SocketAddress
void	clear ()
	Clears the complete address structure.

Protected Attributes
sockaddr_un	m_addr

size_t	m_path_len = 0
	used bytes in m_addr.sun_path excluding terminator

Static Protected Attributes
static constexpr size_t	BASE_SIZE = offsetof(struct sockaddr_un, sun_path)

Detailed Description

Address type for local UNIX domain sockets.

UNIX domain addresses come in three flavours on Linux:

unnamed: these have not been bound to any path. They are either not yet bound or they are anonymous as returned from cosmos::net::create_stream_socket_pair().
path based: an actual file system path is used. The application has to manage the possibility that the path already exists, and has to remove the file system entry when the socket is no longer needed.
abstract: this is a Linux extension. The path starts with a null terminator '\0' (in strings often displayed using a leading '@' character). These sockets don't show up in the file system and are always reference counted i.e. if no process remains using it, the socket is cleaned up automatically. Further '\0' characters in the address have no special meaning, only the size() communicated to the kernel will determine the length of the address.

There is some ambiguity regarding specifying the size of a sockaddr_un in system calls. You can either specify the size of the actual number of bytes used in the structure, or you can specify the full size of the structure. For abstract socket addresses this can become problematic, since \0 characters don't terminate paths here, i.e. if you specify the full size of sockaddr_un then you end up using a different address then when you specify only the actual number of bytes used. For this reason the current implementation only reports the actual number of bytes used for a path. When communicating with applications that follow a different notion here, it can happen that you won't be able to communicate with them.

Warning: File system based sockets are restricted by the permissions of the directory they're placed in, as well by the socket's file mode. Only if a process has write access to the socket, may it connect to it. Sockets living in the abstract namespace, however, have no kernel side permission checking. Any process in the system may connect to them. Thus applications have to check UnixOptions::credentials() for access control.

Definition at line 52 of file UnixAddress.hxx.

Member Typedef Documentation

◆ Abstract

using cosmos::UnixAddress::Abstract = NamedBool<struct abstract_address_t, false>

Strong boolean type to indicate the use an abstract address.

Definition at line 57 of file UnixAddress.hxx.

Constructor & Destructor Documentation

◆ UnixAddress() [1/2]

cosmos::UnixAddress::UnixAddress ( )

inline

Creates an empty address.

Definition at line 62 of file UnixAddress.hxx.

                      {
                m_addr.sun_family = to_integral(family());
                m_addr.sun_path[0] = '\0';
        }

◆ UnixAddress() [2/2]

cosmos::UnixAddress::UnixAddress	(	const std::string_view	path,
		const Abstract	abstract = Abstract{false} )

inlineexplicit

Creates an address from the given path which can also be abstract.

Definition at line 68 of file UnixAddress.hxx.

                                                                                          {false}) :
                        UnixAddress{} {
                setPath(path, abstract);
        }

Member Function Documentation

◆ basePtr() [1/2]

const sockaddr * cosmos::UnixAddress::basePtr ( ) const

inlineoverrideprotectedvirtual

Returns a const pointer to the sockaddr* base structure.

Implements cosmos::SocketAddress.

Definition at line 160 of file UnixAddress.hxx.

                                                 {
                return reinterpret_cast<const sockaddr*>(&m_addr);
        }

◆ basePtr() [2/2]

sockaddr * cosmos::UnixAddress::basePtr ( )

inlineoverrideprotectedvirtual

Returns a mutable pointer to the sockaddr* base structure.

Implements cosmos::SocketAddress.

Definition at line 156 of file UnixAddress.hxx.

                                     {
                return reinterpret_cast<sockaddr*>(&m_addr);
        }

◆ family()

SocketFamily cosmos::UnixAddress::family ( ) const

inlineoverridevirtual

Returns the concrete SocketFamily for the implementation address type.

Implements cosmos::SocketAddress.

Definition at line 73 of file UnixAddress.hxx.

                                             {
                return SocketFamily::UNIX;
        }

◆ getPath()

std::string_view cosmos::UnixAddress::getPath ( ) const

inline

Returns the currently set path.

This returns the string used in setPath(). If an abstract path is currently set then the leading '\0' terminator will not be contained in the string_view.

Definition at line 112 of file UnixAddress.hxx.

                                       {
                if (isAbstract()) {
                        return std::string_view{m_addr.sun_path + 1, m_path_len};
                } else {
                        return std::string_view{m_addr.sun_path, m_path_len};
                }
        }

◆ isAbstract()

bool cosmos::UnixAddress::isAbstract ( ) const

inline

Returns whether currently an abstract path is contained.

Definition at line 130 of file UnixAddress.hxx.

                                {
                return m_path_len > 1 && m_addr.sun_path[0] == '\0';
        }

◆ isUnnamed()

bool cosmos::UnixAddress::isUnnamed ( ) const

inline

Returns whether this address is currently unnamed (empty).

Definition at line 135 of file UnixAddress.hxx.

                               {
                return m_path_len == 0;
        }

◆ label()

std::string cosmos::UnixAddress::label ( ) const

Returns a human readable label for the contained path.

This returns an implementation defined, human readable label describing the currently set path. In particular abstract paths are transformed in a way to indicate their abstract nature. Also unnamed addresses are specially marked in the returned string.

Definition at line 45 of file UnixAddress.cxx.

                                   {
        if (isUnnamed()) {
                return "<unnamed>";
        } else if(isAbstract()) {
                std::string ret;
                ret.push_back('@');
                ret.append(getPath().begin() + 1, m_path_len);
                return ret;
        } else {
                return std::string{getPath()};
        }
}

◆ maxPathLen()

size_t cosmos::UnixAddress::maxPathLen ( ) const

inline

Maximum path length that can be stored in a UnixAddress structure.

The returned value is not counting ‘\0’ terminators. For both abstract and non-abstract addresses one byte for a null terminator (leading or trailing) is subtracted.

Definition at line 93 of file UnixAddress.hxx.

                                  {
                return sizeof(m_addr) - BASE_SIZE - 1;
        }

◆ maxSize()

size_t cosmos::UnixAddress::maxSize ( ) const

inlineoverridevirtual

Returns the maximum address size without taking into account the currently set path.

Reimplemented from cosmos::SocketAddress.

Definition at line 83 of file UnixAddress.hxx.

                                        {
                return sizeof(m_addr);
        }

◆ operator!=()

bool cosmos::UnixAddress::operator!= ( const UnixAddress & other ) const

inline

Definition at line 148 of file UnixAddress.hxx.

                                                        {
                return !(*this == other);
        }

◆ operator==()

bool cosmos::UnixAddress::operator== ( const UnixAddress & other ) const

inline

Definition at line 139 of file UnixAddress.hxx.

                                                        {
                if (m_path_len != other.m_path_len)
                        return false;
                if (m_addr.sun_family != other.m_addr.sun_family)
                        return false;
 
                return std::memcmp(m_addr.sun_path, other.m_addr.sun_path, m_path_len + 1) == 0;
        }

◆ setPath()

void cosmos::UnixAddress::setPath	(	const std::string_view	path,
		const Abstract	abstract = Abstract{false} )

Sets a new path for the address.

Depending on the abstract setting this will be either a file system path, or an abstract label. No '\0' terminators should be embedded into path for the abstract case. The implementation will take care of this transparently.

Definition at line 7 of file UnixAddress.cxx.

                                                                            {
 
        if (path.size() > maxPathLen()) {
                cosmos_throw( RuntimeError("UNIX address path too long") );
        }
 
        char *ptr = m_addr.sun_path;
 
        if (abstract) {
                *ptr = '\0';
                ptr++;
        }
 
        std::memcpy(ptr, path.data(), path.size());
 
        if (!abstract) {
                ptr[path.size()] = '\0';
        }
 
        m_path_len = path.size();
}

◆ size()

size_t cosmos::UnixAddress::size ( ) const

inlineoverridevirtual

Returns the size of the structure considering the currently set path length only.

Implements cosmos::SocketAddress.

Definition at line 78 of file UnixAddress.hxx.

                                     {
                return BASE_SIZE + m_path_len + 1;
        }

◆ update()

void cosmos::UnixAddress::update ( size_t new_length )

overrideprotectedvirtual

Update the address structure after it has been filled in by the kernel.

Some system calls update the address structure. The obtained number of bytes is found in new_length. Some address structures have dynamic sizes in which case the new length has to be accommodated for by overriding this function call.

The default implementation only performs a sanity check that the new length matches the old length (considering statically sized addresses).

Reimplemented from cosmos::SocketAddress.

Definition at line 29 of file UnixAddress.cxx.

                                          {
        if (new_length < BASE_SIZE) {
                m_addr.sun_family = to_integral(family());
                m_path_len = 0;
                cosmos_throw( RuntimeError("short address on update") );
        }
 
        new_length -= BASE_SIZE;
 
        // we don't count the null terminator (leading for abstract path, or
        // trailing for regular path).
        new_length--;
 
        m_path_len = new_length;
}

Member Data Documentation

◆ BASE_SIZE

size_t cosmos::UnixAddress::BASE_SIZE = offsetof(struct sockaddr_un, sun_path)

staticconstexprprotected

Definition at line 166 of file UnixAddress.hxx.

◆ m_addr

sockaddr_un cosmos::UnixAddress::m_addr

protected

Definition at line 167 of file UnixAddress.hxx.

◆ m_path_len

size_t cosmos::UnixAddress::m_path_len = 0

protected

used bytes in m_addr.sun_path excluding terminator

Definition at line 168 of file UnixAddress.hxx.

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

include/net/UnixAddress.hxx
src/net/UnixAddress.cxx

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Abstract

Constructor & Destructor Documentation

◆ UnixAddress() [1/2]

◆ UnixAddress() [2/2]

Member Function Documentation

◆ basePtr() [1/2]

◆ basePtr() [2/2]

◆ family()

◆ getPath()

◆ isAbstract()

◆ isUnnamed()

◆ label()

◆ maxPathLen()

◆ maxSize()

◆ operator!=()

◆ operator==()

◆ setPath()

◆ size()

◆ update()

Member Data Documentation

◆ BASE_SIZE

◆ m_addr

◆ m_path_len