Wraps an OS File descriptor to read and write to and from it. More...

#include <FileDescriptor.h>

Inheritance diagram for SC::FileDescriptor:

Classes
struct	OpenOptions
	Additional flags to be set when opening files. More...

Public Types
enum	OpenMode { ReadOnly , WriteCreateTruncate , WriteAppend , ReadAndWrite }
	Define mode for opening the file (read, write etc.) More...

enum	SeekMode { SeekStart , SeekEnd , SeekCurrent }
	How the offset to FileDescriptor::seek is defined. More...

Public Member Functions
Result	open (StringView path, OpenMode mode)
	Opens file at `path` with a given `mode` More...

Result	open (StringView path, OpenMode mode, OpenOptions options)
	Opens file at `path` with a given `mode` More...

Result	setBlocking (bool blocking)
	Set blocking mode (read / write waiting for I/O). More...

Result	setInheritable (bool inheritable)
	Set inheritable flag (visibility to child processes). More...

Result	isInheritable (bool &hasValue) const
	Queries the inheritable state of this descriptor. More...

Result	read (Span< char > data, Span< char > &actuallyRead, uint64_t offset)
	Reads bytes at offset into user supplied span. More...

Result	read (Span< uint8_t > data, Span< uint8_t > &actuallyRead, uint64_t offset)
	Reads bytes at offset into user supplied span. More...

Result	read (Span< char > data, Span< char > &actuallyRead)
	Reads bytes from current position (FileDescriptor::seek) into user supplied Span. More...

Result	read (Span< uint8_t > data, Span< uint8_t > &actuallyRead)
	Reads bytes from current position (FileDescriptor::seek) into user supplied Span. More...

Result	write (Span< const char > data, uint64_t offset)
	Writes bytes at offset from start of the file descriptor. More...

Result	write (Span< const uint8_t > data, uint64_t offset)
	Writes bytes at offset from start of the file descriptor. More...

Result	write (Span< const char > data)
	Writes bytes from current position (FileDescriptor::seek) of the file descriptor. More...

Result	write (Span< const uint8_t > data)
	Writes bytes from current position (FileDescriptor::seek) of the file descriptor. More...

Result	seek (SeekMode seekMode, uint64_t offset)
	Changes the current position in the file descriptor, if seekable. More...

Result	currentPosition (size_t &position) const
	Gets current descriptor position (if seekable) More...

Result	sizeInBytes (size_t &sizeInBytes) const
	Gets total file size in bytes (if seekable) More...

Result	readUntilEOF (Vector< char > &destination)
	Reads into a given dynamic buffer until End of File (EOF) is signaled. More...

Result	readUntilEOF (Vector< uint8_t > &destination)
	Reads into a given dynamic buffer until End of File (EOF) is signaled. More...

Result	readUntilEOF (String &destination)
	Reads into a given string until End of File (EOF) is signaled Works also for non-seekable file descriptors (stdout / in / err). More...

	UniqueHandle ()=default

	UniqueHandle (const UniqueHandle &v)=delete

	UniqueHandle (UniqueHandle &&v)

	UniqueHandle (const Handle &externalHandle)

Detailed Description

Wraps an OS File descriptor to read and write to and from it.

Example usage:

    StringNative<255> filePath = StringEncoding::Native;
    StringNative<255> dirPath  = StringEncoding::Native;
    // Setup the test
    FileSystem fs;
 
    const StringView name     = "FileDescriptorTest";
    const StringView fileName = "test.txt";
    SC_TEST_EXPECT(Path::join(dirPath, {report.applicationRootDirectory, name}));
    SC_TEST_EXPECT(Path::join(filePath, {dirPath.view(), fileName}));
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory));
    SC_TEST_EXPECT(fs.makeDirectory(name));
    SC_TEST_EXPECT(fs.changeDirectory(dirPath.view()));
 
    // Open a file, write and close it
    FileDescriptor fd;
    SC_TEST_EXPECT(fd.open(filePath.view(), FileDescriptor::WriteCreateTruncate));
    SC_TEST_EXPECT(fd.write(StringView("test").toCharSpan()));
    SC_TEST_EXPECT(fd.close());
 
    // Re-open the file for read
    SC_TEST_EXPECT(fd.open(filePath.view(), FileDescriptor::ReadOnly));
 
    // Read some data from the file
    char       buffer[4] = {0};
    Span<char> spanOut;
    SC_TEST_EXPECT(fd.read({buffer, sizeof(buffer)}, spanOut));
    SC_TEST_EXPECT(fd.close());
 
    // Check if read content matches
    StringView sv(spanOut, false, StringEncoding::Ascii);
    SC_TEST_EXPECT(sv.compare("test") == StringView::Comparison::Equals);
 
    // Shutdown test
    SC_TEST_EXPECT(fs.removeFile(fileName));
    SC_TEST_EXPECT(fs.changeDirectory(report.applicationRootDirectory));
    SC_TEST_EXPECT(fs.removeEmptyDirectory(name));

Member Enumeration Documentation

◆ OpenMode

enum SC::FileDescriptor::OpenMode

Define mode for opening the file (read, write etc.)

Enumerator
ReadOnly	Opens in read-only mode.
WriteCreateTruncate	Opens in write mode, creating or truncating it if another file exists at same location.
WriteAppend	Opens write mode, appending to existing file that must exist at the same location.
ReadAndWrite	Opens file for read / write mode.

◆ SeekMode

enum SC::FileDescriptor::SeekMode

How the offset to FileDescriptor::seek is defined.

Enumerator
SeekStart	Offset to FileDescriptor::seek is to be applied from start of descriptor.
SeekEnd	Offset to FileDescriptor::seek is to be applied (backwards) from end of descriptor.
SeekCurrent	Offset to FileDescriptor::seek is to be applied from current descriptor position.

Member Function Documentation

◆ currentPosition()

Result SC::FileDescriptor::currentPosition ( size_t & position ) const

Gets current descriptor position (if seekable)

Parameters

position (output) current position of file descriptor

Returns: Valid result if seek succeeds

◆ isInheritable()

Result SC::FileDescriptor::isInheritable ( bool & hasValue ) const

Queries the inheritable state of this descriptor.

Parameters

hasValue will be set to true if the file descriptor has inheritable file set

Returns: Valid Result if the inheritable flag has been queried successfully

◆ open() [1/2]

Result SC::FileDescriptor::open	(	StringView	path,
		OpenMode	mode
	)

Opens file at path with a given mode

Parameters

path	The path to file
mode	The mode used to open file (read-only, write-append etc.)

Returns: Valid Result if file is opened successfully

◆ open() [2/2]

Result SC::FileDescriptor::open	(	StringView	path,
		OpenMode	mode,
		OpenOptions	options
	)

Opens file at path with a given mode

Parameters

path	The path to file
mode	The mode used to open file
options	Options that can be applied when opening the file (inheritable, blocking etc.)

Returns: Valid Result if file is opened successfully

◆ read() [1/4]

Result SC::FileDescriptor::read	(	Span< char >	data,
		Span< char > &	actuallyRead
	)

Reads bytes from current position (FileDescriptor::seek) into user supplied Span.

Parameters

data	Span of bytes where data should be written to
actuallyRead	A sub-span of data of the actually read bytes. A zero sized span means EOF.

Returns: Valid result if read succeeded

◆ read() [2/4]

Result SC::FileDescriptor::read	(	Span< char >	data,
		Span< char > &	actuallyRead,
		uint64_t	offset
	)

Reads bytes at offset into user supplied span.

Parameters

data	Span of bytes where data should be written to
actuallyRead	A sub-span of data of the actually read bytes. A zero sized span means EOF.
offset	Offset from begin of the file descriptor where read should be started

Returns: Valid result if read succeeded

◆ read() [3/4]

Result SC::FileDescriptor::read	(	Span< uint8_t >	data,
		Span< uint8_t > &	actuallyRead
	)

Reads bytes from current position (FileDescriptor::seek) into user supplied Span.

Parameters

data	Span of bytes where data should be written to
actuallyRead	A sub-span of data of the actually read bytes. A zero sized span means EOF.

Returns: Valid result if read succeeded

◆ read() [4/4]

Result SC::FileDescriptor::read	(	Span< uint8_t >	data,
		Span< uint8_t > &	actuallyRead,
		uint64_t	offset
	)

Reads bytes at offset into user supplied span.

Parameters

data	Span of bytes where data should be written to
actuallyRead	A sub-span of data of the actually read bytes. A zero sized span means EOF.
offset	Offset from begin of the file descriptor where read should be started

Returns: Valid result if read succeeded

◆ readUntilEOF() [1/3]

Result SC::FileDescriptor::readUntilEOF ( String & destination )

Reads into a given string until End of File (EOF) is signaled Works also for non-seekable file descriptors (stdout / in / err).

Parameters

destination A destination string to write to (it will be sized as needed)

Returns: Valid result if read succeeded until EOF

◆ readUntilEOF() [2/3]

Result SC::FileDescriptor::readUntilEOF ( Vector< char > & destination )

Reads into a given dynamic buffer until End of File (EOF) is signaled.

Works also for non-seekable file descriptors (stdout / in / err).

Parameters

destination A destination buffer to write to (it will be resized as needed)

Returns: Valid result if read succeeded until EOF

◆ readUntilEOF() [3/3]

Result SC::FileDescriptor::readUntilEOF ( Vector< uint8_t > & destination )

Reads into a given dynamic buffer until End of File (EOF) is signaled.

Works also for non-seekable file descriptors (stdout / in / err).

Parameters

destination A destination buffer to write to (it will be resized as needed)

Returns: Valid result if read succeeded until EOF

◆ seek()

Result SC::FileDescriptor::seek	(	SeekMode	seekMode,
		uint64_t	offset
	)

Changes the current position in the file descriptor, if seekable.

Parameters

seekMode	How the offset is defined (from start, end, current)
offset	An offset to be applied according to seekMode to this descriptor

Returns: Valid result if seek succeeds

◆ setBlocking()

Result SC::FileDescriptor::setBlocking ( bool blocking )

Set blocking mode (read / write waiting for I/O).

Can be set also during open with OpenOptions.

Parameters

blocking true to set file to blocking mode

Returns: true if blocking mode has been changed successfully

◆ setInheritable()

Result SC::FileDescriptor::setInheritable ( bool inheritable )

Set inheritable flag (visibility to child processes).

Can be set also during open with OpenOptions.

Parameters

inheritable true to set file to blocking mode

Returns: true if blocking mode has been changed successfully

◆ sizeInBytes()

Result SC::FileDescriptor::sizeInBytes ( size_t & sizeInBytes ) const

Gets total file size in bytes (if seekable)

Parameters

sizeInBytes (output) total size of file

Returns: Valid result if seek succeeds

◆ write() [1/4]

Result SC::FileDescriptor::write ( Span< const char > data )

Writes bytes from current position (FileDescriptor::seek) of the file descriptor.

Parameters

data	Span of bytes containing the data to write

Returns: Valid result if write succeeded

◆ write() [2/4]

Result SC::FileDescriptor::write	(	Span< const char >	data,
		uint64_t	offset
	)

Writes bytes at offset from start of the file descriptor.

Parameters

data	Span of bytes containing the data to write
offset	Offset from begin of file descriptor to start writing

Returns: Valid result if write succeeded

◆ write() [3/4]

Result SC::FileDescriptor::write ( Span< const uint8_t > data )

Writes bytes from current position (FileDescriptor::seek) of the file descriptor.

Parameters

data	Span of bytes containing the data to write

Returns: Valid result if write succeeded

◆ write() [4/4]

Result SC::FileDescriptor::write	(	Span< const uint8_t >	data,
		uint64_t	offset
	)

Writes bytes at offset from start of the file descriptor.

Parameters

data	Span of bytes containing the data to write
offset	Offset from begin of file descriptor to start writing

Returns: Valid result if write succeeded

The documentation for this struct was generated from the following file:

FileDescriptor.h

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ OpenMode

◆ SeekMode

Member Function Documentation

◆ currentPosition()

◆ isInheritable()

◆ open() [1/2]

◆ open() [2/2]

◆ read() [1/4]

◆ read() [2/4]

◆ read() [3/4]

◆ read() [4/4]

◆ readUntilEOF() [1/3]

◆ readUntilEOF() [2/3]

◆ readUntilEOF() [3/3]

◆ seek()

◆ setBlocking()

◆ setInheritable()

◆ sizeInBytes()

◆ write() [1/4]

◆ write() [2/4]

◆ write() [3/4]

◆ write() [4/4]