Client side socket for connection mode UNIX domain sockets. More...

#include <UnixClientSocket.hxx>

Inheritance diagram for cosmos::UnixClientSocket:

Public Types
using	Connection = UnixConnection

Public Types inherited from cosmos::Socket
enum class	Direction : int { READ = SHUT_RD , WRITE = SHUT_WR , READ_WRITE = SHUT_RDWR }
	Type used in Socket::shutdown(). More...

using	AddressFilledIn = NamedBool<struct addr_filled_in_t, false>
	Boolean flag used in receiveFrom() to signify if a peer address could be provided.

Public Types inherited from cosmos::StreamIO
enum class	SeekType : int { SET = SEEK_SET , CUR = SEEK_CUR , END = SEEK_END , DATA = SEEK_DATA , HOLE = SEEK_HOLE }
	Different methods for changing the file read/write position. More...

Public Member Functions
	UnixClientSocket (const SocketType type, const SocketFlags flags=SocketFlags{SocketFlag::CLOEXEC})

auto	unixOptions ()

auto	unixOptions () const

void	getSockName (UnixAddress &addr)
	Returns the current address that the socket is bound to, if any.

void	bind (const UnixAddress &addr)
	Bind to the given UNIX address.

UnixConnection	connect (const UnixAddress &addr)
	Connect to the given UNIX address.

Public Member Functions inherited from cosmos::Socket
auto	sockOptions ()

auto	sockOptions () const

void	getSockName (SocketAddress &addr)
	Returns the current address that the socket is bound to, if any.

void	shutdown (const Direction dir)
	Shutdown part or all of the connection on protocol level.

Public Member Functions inherited from cosmos::FDFile
	FDFile (const FileDescriptor fd, const AutoCloseFD auto_close)
	Wrap the given file descriptor applying the specified auto-close behaviour.

	FDFile (FDFile &&other) noexcept

FDFile &	operator= (FDFile &&other) noexcept

void	open (const FileDescriptor fd, const AutoCloseFD auto_close)
	Takes the already open file descriptor fd and operates on it.

void	close () override
	Close the current file object.

Public Member Functions inherited from cosmos::FileBase
	FileBase (const FileBase &)=delete

FileBase &	operator= (const FileBase &)=delete

bool	isOpen () const
	Returns whether currently a FileDescriptor is opened.

FileDescriptor	fd () const
	Allows access to the underlying fd with const semantics.

void	truncate (const off_t length)

Public Member Functions inherited from cosmos::StreamIO
	StreamIO (FileDescriptor &fd)

	StreamIO (const StreamIO &)=delete

StreamIO &	operator= (const StreamIO &)=delete

StreamIO &	operator= (StreamIO &&) noexcept

size_t	read (void *buf, size_t length)
	Read up to `length` bytes from the file into `buf`.

size_t	write (const void *buf, size_t length)
	Write up to `length` bytes from `buf` into the underlying file.

size_t	write (const std::string_view data)
	string_view wrapper around write(const void*, size_t).

void	readAll (void *buf, size_t length)
	Read all `length` bytes from the underlying file.

void	readAll (std::string &s, size_t length)
	Like readAll(void*, size_t) using an STL string.

void	writeAll (const void *buf, size_t length)
	Write all `length` bytes into the underlying file.

void	writeAll (const std::string_view data)
	string_view wrapper around writeAll(const void*, size_t).

bool	read (ReadIOVector &iovec)
	Read data from file into a vector of data regions.

bool	write (WriteIOVector &iovec)
	Write data to file from a vector of data regions.

void	readAll (ReadIOVector &iovec)
	Read into all data regions specified in `iovec`.

void	writeAll (WriteIOVector &iovec)
	Write all data regions specified in `iovec`.

off_t	seek (const SeekType type, off_t off)
	Seek to the given offset based on the given offset `type`.

off_t	seekFromStart (off_t off)
	Seek to the given offset relative to the start of the file.

off_t	seekFromCurrent (off_t off)
	Seek to the given offset relative to the current file position.

off_t	seekFromEnd (off_t off)
	Seek to the given offset relative to the end of the file.

Protected Member Functions
size_t	read (void *buf, size_t length)
	Read up to `length` bytes from the file into `buf`.

bool	read (ReadIOVector &iovec)
	Read data from file into a vector of data regions.

void	readAll (void *buf, size_t length)
	Read all `length` bytes from the underlying file.

void	readAll (std::string &s, size_t length)
	Like readAll(void*, size_t) using an STL string.

void	readAll (ReadIOVector &iovec)
	Read into all data regions specified in `iovec`.

size_t	write (const void *buf, size_t length)
	Write up to `length` bytes from `buf` into the underlying file.

size_t	write (const std::string_view data)
	string_view wrapper around write(const void*, size_t).

bool	write (WriteIOVector &iovec)
	Write data to file from a vector of data regions.

void	writeAll (const void *buf, size_t length)
	Write all `length` bytes into the underlying file.

void	writeAll (const std::string_view data)
	string_view wrapper around writeAll(const void*, size_t).

void	writeAll (WriteIOVector &iovec)
	Write all data regions specified in `iovec`.

Protected Member Functions inherited from cosmos::Socket
	Socket (const SocketFamily family, const SocketType type, const SocketFlags flags=SocketFlags{SocketFlag::CLOEXEC}, const SocketProtocol protocol=SocketProtocol::DEFAULT)
	Creates a new socket using the given properties.

	Socket (FileDescriptor fd, const AutoCloseFD auto_close)
	Creates a new socket from the given existing file descriptor.

void	bind (const SocketAddress &addr)
	Bind the socket to the given local address.

void	connect (const SocketAddress &addr)
	Establish a new connection using the given destination address.

void	listen (const size_t backlog)
	Enter into a passive listen state, allowing new connections.

FileDescriptor	accept (SocketAddress *addr)
	Accept a new connection on the socket.

size_t	send (const void *buf, size_t length, const MessageFlags flags=MessageFlags{})
	Send the given data over the socket, using specific send flags.

size_t	send (const std::string_view data, const MessageFlags flags=MessageFlags{})
	Variant of send() that takes a std::string_view container instead of a raw input buffer.

size_t	sendTo (const void *buf, size_t length, const SocketAddress &addr, const MessageFlags flags=MessageFlags{})
	Send a packet to a specific destination address.

size_t	sendTo (const std::string_view data, const SocketAddress &addr, const MessageFlags flags=MessageFlags{})
	Variant of sendTo() that takes a std::string_view container instead of a raw input buffer.

void	sendMessage (SendMessageHeader &header, const SocketAddress *addr=nullptr)
	Sends a message over the socket using extended SendMessageHeader data.

size_t	receive (void *buf, size_t length, const MessageFlags flags=MessageFlags{})
	Receive data from the socket, using specific receive flags.

std::pair< size_t, AddressFilledIn >	receiveFrom (void *buf, size_t length, SocketAddress &addr, const MessageFlags flags=MessageFlags{})
	Receive a packet, filling in the sender's address.

AddressFilledIn	receiveMessage (ReceiveMessageHeader &header, SocketAddress *addr=nullptr)
	Receives a message from the socket using extended ReceiveMessageHeader data.

Protected Member Functions inherited from cosmos::FileBase
	FileBase (const FileDescriptor fd=FileDescriptor{})

	FileBase (FileBase &&other) noexcept

FileBase &	operator= (FileBase &&other) noexcept

Additional Inherited Members
Protected Attributes inherited from cosmos::FDFile
AutoCloseFD	m_auto_close

Protected Attributes inherited from cosmos::FileBase
FileDescriptor	m_fd

Protected Attributes inherited from cosmos::StreamIO
FileDescriptor &	m_stream_fd

Detailed Description

Client side socket for connection mode UNIX domain sockets.

The send and receive I/O functions are not available on this level. connect() will return a UnixConnection type that represents an existing connection and corresponding I/O methods.

For the server side listening socket look at the UnixListenSocket.

Definition at line 17 of file UnixClientSocket.hxx.

Member Typedef Documentation

◆ Connection

using cosmos::UnixClientSocket::Connection = UnixConnection

Definition at line 21 of file UnixClientSocket.hxx.

Constructor & Destructor Documentation

◆ UnixClientSocket()

cosmos::UnixClientSocket::UnixClientSocket	(	const SocketType	type,
		const SocketFlags	flags = SocketFlags{SocketFlag::CLOEXEC} )

explicit

Definition at line 7 of file UnixClientSocket.cxx.

                                                                                 :
                Socket{SocketFamily::UNIX, type, flags} {
        if (type != SocketType::STREAM && type != SocketType::SEQPACKET) {
                cosmos_throw(RuntimeError("invalid socket type for unix connection mode socket"));
        }
}

Member Function Documentation

◆ bind()

void cosmos::UnixClientSocket::bind ( const UnixAddress & addr )

inline

Bind to the given UNIX address.

Explicitly bind to a local UNIX address. This is usually not necessary for client side sockets. The operating system will automatically select a proper local address when connecting to a remote party. In some cases this can be helpful to have full control over the local address, though.

See also: Socket::bind

Definition at line 50 of file UnixClientSocket.hxx.

                                           {
                return Socket::bind(addr);
        }

◆ connect()

UnixConnection cosmos::UnixClientSocket::connect ( const UnixAddress & addr )

inline

Connect to the given UNIX address.

By connecting a UNIX client socket, a connection is established. After this is done send() and receive() can be used to exchange data on the connection.

Normally if the call returns successfully then the connection has been established. Special rules apply if the socket is in non-blocking mode, though.

After a successful return the ownership of the socket file descriptor is transferred to the connection instance, and the client socket will no longer be valid for use.

See also: Socket::connect()

Definition at line 70 of file UnixClientSocket.hxx.

                                                        {
                Socket::connect(addr);
                auto ret = UnixConnection{this->m_fd};
                this->m_fd.reset();
                return ret;
        }

◆ getSockName()

void cosmos::UnixClientSocket::getSockName ( UnixAddress & addr )

inline

Returns the current address that the socket is bound to, if any.

Definition at line 36 of file UnixClientSocket.hxx.

                                            {
                Socket::getSockName(addr);
        }

◆ read() [1/2]

bool cosmos::StreamIO::read ( ReadIOVector & iovec )

protected

Read data from file into a vector of data regions.

The iovec specifies memory regions into which data from the file should be written. The data will be filled sequentially starting from the first memory region.

Partial reads can occur, thus on return the length and base fields of each vector entry will be updated to reflect this. The return value is a flag indicating whether the complete vector has been filled, or whether a partial read occurred.

These vector I/O operations are useful when structured binary of fixed size is transferred e.g. in network protocols for the different header layers. This way the individual headers can be kept in distinct places while only a single system call is necessary to transfer them.

Definition at line 168 of file StreamIO.cxx.

                                       {
        while (true) {
                const auto res = ::readv(
                                to_integral(m_stream_fd.raw()), iovec.raw(), iovec.size());
 
                if (res < 0) {
                        handleIOError("reading to vector from file");
                        continue;
                }
 
                return iovec.update(static_cast<size_t>(res));
        }
}

◆ read() [2/2]

size_t cosmos::StreamIO::read	(	void *	buf,
		size_t	length )

protected

Read up to length bytes from the file into buf.

An attempt is made to read data from the underlying file object and place it into buf. buf needs to be able to hold at least length bytes. Short reads can occur in which case less bytes will be read. The number of bytes actually read is returned from this function.

A return value of zero indicates that the End-of-File has been reached and no further data can be obtained.

On error conditions an exception is thrown.

Definition at line 93 of file StreamIO.cxx.

                                              {
        while (true) {
                auto res = ::read(to_integral(m_stream_fd.raw()), buf, length);
 
                if (res < 0) {
                        handleIOError("reading from file");
                        continue;
                }
 
                return static_cast<size_t>(res);
        }
}

◆ readAll() [1/3]

void cosmos::StreamIO::readAll ( ReadIOVector & iovec )

inlineprotected

Read into all data regions specified in iovec.

This is just like read(IOVector&) but it takes care of partial reads and continues until all data of the IOVector has been filled or an error occurs. On return the complete vector has been filled.

Definition at line 189 of file StreamIO.hxx.

                                          {
                while (!read(iovec)) {
                        ;
                }
        }

◆ readAll() [2/3]

void cosmos::StreamIO::readAll	(	std::string &	s,
		size_t	length )

inlineprotected

Like readAll(void*, size_t) using an STL string.

Definition at line 125 of file StreamIO.hxx.

                                                  {
                s.resize(length);
                try {
                        readAll(s.data(), length);
                } catch(...) {
                        s.clear();
                        throw;
                }
        }

◆ readAll() [3/3]

void cosmos::StreamIO::readAll	(	void *	buf,
		size_t	length )

protected

Read all length bytes from the underlying file.

This behaves just like read() with the exception that on short reads the operation will be continued until all length bytes have been obtained from the file.

An End-of-File condition is considered an error in this context and results in a RuntimeError exception. If the function returns normally then all length bytes will have been obtained.

Definition at line 122 of file StreamIO.cxx.

                                               {
        size_t res;
        while (length != 0) {
                res = read(buf, length);
                buf = reinterpret_cast<char*>(buf) + res;
                length -= res;
 
                if (res == 0) {
                        cosmos_throw (RuntimeError("unexpected EOF"));
                }
        }
}

◆ unixOptions() [1/2]

auto cosmos::UnixClientSocket::unixOptions ( )

inline

Definition at line 27 of file UnixClientSocket.hxx.

                           {
                return UnixOptions{this->m_fd};
        }

◆ unixOptions() [2/2]

auto cosmos::UnixClientSocket::unixOptions ( ) const

inline

Definition at line 31 of file UnixClientSocket.hxx.

                                 {
                return UnixOptions{this->m_fd};
        }

◆ write() [1/3]

size_t cosmos::StreamIO::write ( const std::string_view data )

inlineprotected

string_view wrapper around write(const void*, size_t).

Definition at line 108 of file StreamIO.hxx.

                                                {
                return write(data.data(), data.size());
        }

◆ write() [2/3]

size_t cosmos::StreamIO::write	(	const void *	buf,
		size_t	length )

protected

Write up to length bytes from buf into the underlying file.

An attempt is made to write data from the given buf and pass it to the underlying file object. buf needs to hold at least length bytes of data. Short writes can occur in which case less bytes will be written. The number of bytes actually written is returned from this function.

On error conditions an exception is thrown.

Definition at line 105 of file StreamIO.cxx.

                                                     {
        while (true) {
                auto res = ::write(to_integral(m_stream_fd.raw()), buf, length);
 
                if (res < 0) {
                        handleIOError("writing to file");
                        continue;
                }
 
                return static_cast<size_t>(res);
        }
}

◆ write() [3/3]

bool cosmos::StreamIO::write ( WriteIOVector & iovec )

protected

Write data to file from a vector of data regions.

The iovec specifies memory regions whose data will be written to the file. The data will be written sequentially starting from the first memory region.

Partial writes can occur, thus on return the length and base fields of each vector entry will be updated to reflect this. The return value is a flag indicating whether the complete vector has been written out, or whether a partial write occurred.

Definition at line 181 of file StreamIO.cxx.

                                         {
        while (true) {
                auto res = ::writev(to_integral(m_stream_fd.raw()), iovec.raw(), iovec.size());
 
                if (res < 0) {
                        handleIOError("writing vector to file");
                        continue;
                }
 
                return iovec.update(static_cast<size_t>(res));
        }
}

◆ writeAll() [1/3]

void cosmos::StreamIO::writeAll ( const std::string_view data )

inlineprotected

string_view wrapper around writeAll(const void*, size_t).

Definition at line 147 of file StreamIO.hxx.

                                                 {
                return writeAll(data.data(), data.size());
        }

◆ writeAll() [2/3]

void cosmos::StreamIO::writeAll	(	const void *	buf,
		size_t	length )

protected

Write all length bytes into the underlying file.

This behaves just like write() with the exception that on short writes the operation will be continued until all length bytes have been written to the file.

If the function returns normally then all length bytes will have been transferred.

Definition at line 144 of file StreamIO.cxx.

                                                      {
        size_t res;
 
        while (length != 0) {
                res = write(buf, length);
                buf = reinterpret_cast<const char*>(buf) + res;
                length -= res;
        }
}

◆ writeAll() [3/3]

void cosmos::StreamIO::writeAll ( WriteIOVector & iovec )

inlineprotected

Write all data regions specified in iovec.

This is just like write(const IOVector&) but it takes care of partial writes and continues until all data of the IOVector has been written out or an error occurs. On return the complete vector has been written.

Definition at line 202 of file StreamIO.hxx.

                                            {
                while (!write(iovec)) {
                        ;
                }
        }

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

include/net/UnixClientSocket.hxx
src/net/UnixClientSocket.cxx

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Connection

Constructor & Destructor Documentation

◆ UnixClientSocket()

Member Function Documentation

◆ bind()

◆ connect()

◆ getSockName()

◆ read() [1/2]

◆ read() [2/2]

◆ readAll() [1/3]

◆ readAll() [2/3]

◆ readAll() [3/3]

◆ unixOptions() [1/2]

◆ unixOptions() [2/2]

◆ write() [1/3]

◆ write() [2/3]

◆ write() [3/3]

◆ writeAll() [1/3]

◆ writeAll() [2/3]

◆ writeAll() [3/3]