Base class for connection based listening-only sockets. More...

#include <ListenSocket.hxx>

Inheritance diagram for cosmos::ListenSocket:

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

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
	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.

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
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...

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

Base class for connection based listening-only sockets.

This base class is only used for connection based socket types. This is further limited to sockets that accept new incoming connections but aren't used for any actual payload I/O (server side sockets).

Definition at line 14 of file ListenSocket.hxx.

Member Function Documentation

◆ listen()

void cosmos::Socket::listen ( const size_t backlog )

Enter into a passive listen state, allowing new connections.

This is only possible for connection mode socket types, when you want to accept new connections. For client side sockets this is not necessary.

Parameters

[in] backlog The number of pending connections that may be queued in the kernel.

Definition at line 127 of file Socket.cxx.

                                        {
        if (::listen(to_integral(m_fd.raw()), backlog) != 0) {
                cosmos_throw (ApiError("listen()"));
        }
}

◆ 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"));
                }
        }
}

◆ Socket() [1/2]

cosmos::Socket::Socket	(	const SocketFamily	family,
		const SocketType	type,
		const SocketFlags	flags = SocketFlags{SocketFlag::CLOEXEC},
		const SocketProtocol	protocol = SocketProtocol::DEFAULT )

protected

Creates a new socket using the given properties.

Definition at line 79 of file Socket.cxx.

                                               {
        auto fd = ::socket(
                        to_integral(family),
                        to_integral(type) | flags.raw(),
                        to_integral(protocol));
        m_fd.setFD(FileNum{fd});
 
        if (!m_fd.valid()) {
                cosmos_throw(ApiError("socket()"));
        }
}

◆ Socket() [2/2]

cosmos::Socket::Socket	(	FileDescriptor	fd,
		const AutoCloseFD	auto_close )

inlineprotected

Creates a new socket from the given existing file descriptor.

Definition at line 86 of file Socket.hxx.

                                                                :
                        FDFile{fd, auto_close}
        {}

◆ 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 file:

include/net/ListenSocket.hxx

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ listen()

◆ read() [1/2]

◆ read() [2/2]

◆ readAll() [1/3]

◆ readAll() [2/3]

◆ readAll() [3/3]

◆ Socket() [1/2]

◆ Socket() [2/2]

◆ write() [1/3]

◆ write() [2/3]

◆ write() [3/3]

◆ writeAll() [1/3]

◆ writeAll() [2/3]

◆ writeAll() [3/3]