Wrapper around file descriptors for streaming I/O access. More...

#include <StreamIO.hxx>

Inheritance diagram for cosmos::StreamIO:

Public Types
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
	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 Attributes
FileDescriptor &	m_stream_fd

Detailed Description

Wrapper around file descriptors for streaming I/O access.

Streaming I/O means that a file's read/write position is maintained by the operating system and data is exchanged by means of read/write operations that transfer data from the current process to the file and vice versa.

This is the most common access mode for files but also somewhat inefficient. In contrast e.g. memory mapped files can be more efficient.

Some special devices or file types may also support streaming I/O access. This type can also be used with them - but be sure to understand the special I/O semantics for the respective file type when using it with this wrapper.

Beyond read and write operations this type also offers seek operations. Not all file types are seekable though and the operation can fail.

This type will not take ownership of the provided file descriptor. It is only meant as an access wrapper, not as a permanent representation of the backed file.

StreamIO has a fixed coupling to the assigned file descriptor. It can be used as a mixin class or as a base class.

Definition at line 40 of file StreamIO.hxx.

Member Enumeration Documentation

◆ SeekType

enum class cosmos::StreamIO::SeekType : int

strong

Different methods for changing the file read/write position.

Enumerator
SET	Set a new absolute position.
CUR	Set a position relative to the current one.
END	Set a position relative to the end of the file. Seek to a non-hole position.
DATA	For files with holes in them this seeks the next position containing data that is equal or greater to the provided offset.
HOLE	Seek to a hole position. For files with holes in them this seeks the next position that is part of a hole that is equal or greater to the provided offset. The end-of-file is considered a whole in this context.

Definition at line 44 of file StreamIO.hxx.

                            : int {
                SET = SEEK_SET, 
                CUR = SEEK_CUR, 
                END = SEEK_END, 
 
                DATA = SEEK_DATA,
 
                HOLE = SEEK_HOLE
        };

Constructor & Destructor Documentation

◆ StreamIO()

cosmos::StreamIO::StreamIO ( FileDescriptor & fd )

inlineexplicit

Definition at line 67 of file StreamIO.hxx.

                                              :
                        m_stream_fd{fd}
        {}

Member Function Documentation

◆ operator=()

StreamIO & cosmos::StreamIO::operator= ( StreamIO && )

inlinenoexcept

Definition at line 74 of file StreamIO.hxx.

                                                  {
                // simply do nothing, the fixed coupling to the FD remains and
                // should reflect the new object state.
                return *this;
        }

◆ read() [1/2]

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

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 75 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 )

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 26 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 )

inline

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 )

inline

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 )

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

◆ seek()

off_t cosmos::StreamIO::seek	(	const SeekType	type,
		off_t	off )

Seek to the given offset based on the given offset type.

Definition at line 102 of file StreamIO.cxx.

                                                   {
        const auto res = ::lseek(to_integral(m_stream_fd.raw()), off, to_integral(type));
 
        if (res == static_cast<off_t>(-1)) {
                cosmos_throw (ApiError("lseek()"));
        }
 
        return res;
}

◆ seekFromCurrent()

off_t cosmos::StreamIO::seekFromCurrent ( off_t off )

inline

Seek to the given offset relative to the current file position.

Definition at line 214 of file StreamIO.hxx.

214{ return seek(SeekType::CUR, off); }

cosmos::StreamIO::seek

off_t seek(const SeekType type, off_t off)

Seek to the given offset based on the given offset type.

Definition StreamIO.cxx:102

◆ seekFromEnd()

off_t cosmos::StreamIO::seekFromEnd ( off_t off )

inline

Seek to the given offset relative to the end of the file.

Definition at line 216 of file StreamIO.hxx.

216{ return seek(SeekType::END, off); }

◆ seekFromStart()

off_t cosmos::StreamIO::seekFromStart ( off_t off )

inline

Seek to the given offset relative to the start of the file.

Definition at line 212 of file StreamIO.hxx.

212{ return seek(SeekType::SET, off); }

◆ write() [1/3]

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

inline

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 )

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 52 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 )

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 89 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 )

inline

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 )

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 65 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 )

inline

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)) {
                        ;
                }
        }

Member Data Documentation

◆ m_stream_fd

FileDescriptor& cosmos::StreamIO::m_stream_fd

protected

Definition at line 220 of file StreamIO.hxx.

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

include/io/StreamIO.hxx
src/io/StreamIO.cxx

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ SeekType

Constructor & Destructor Documentation

◆ StreamIO()

Member Function Documentation

◆ operator=()

◆ read() [1/2]

◆ read() [2/2]

◆ readAll() [1/3]

◆ readAll() [2/3]

◆ readAll() [3/3]

◆ seek()

◆ seekFromCurrent()

◆ seekFromEnd()

◆ seekFromStart()

◆ write() [1/3]

◆ write() [2/3]

◆ write() [3/3]

◆ writeAll() [1/3]

◆ writeAll() [2/3]

◆ writeAll() [3/3]

Member Data Documentation

◆ m_stream_fd