File

Table of Contents

• Features
• Status
• Description
• Roadmap

🟩 Synchronous Disk File I/O

File library allows synchronous I/O operations on files and pipes.

Features

SC::FileDescriptor	Wraps an OS File descriptor to read and write to and from it.
SC::FileDescriptor::open	Opens file at path with a given mode
SC::FileDescriptor::read	Reads bytes at offset into user supplied span.
SC::FileDescriptor::write	Writes bytes at offset from start of the file descriptor.
SC::FileDescriptor::seek	Changes the current position in the file descriptor, if seekable.
SC::FileDescriptor::readUntilEOF	Reads into a given dynamic buffer until End of File (EOF) is signaled.

SC::PipeDescriptor	Descriptor representing a Pipe used for InterProcess Communication (IPC)
SC::PipeDescriptor::readPipe	The read side of the pipe.
SC::PipeDescriptor::writePipe	The write side of the pipe.

Status

🟩 Usable
This library has a relatively limited scope and it should not need many additional features compared to now.
Will consider bumping to Complete in the future.

Description

SC::FileDescriptor object can be created by SC::FileDescriptor::open-ing a path on file system and it can be SC::FileDescriptor::read or SC::FileDescriptor::write.
Also non-blocking mode can be controlled with SC::FileDescriptor::setBlocking.
A file can be marked as inheritable with SC::FileDescriptor::setInheritable so that in can be accessed by child processes. SC::PipeDescriptor creates a pipe for InterProcess communication.
A pipe has read and write SC::FileDescriptor endpoints and it's used by Process library to redirect standard input, output or error to other processes.
It can also be used to read or write the standard input, output or error from current process into a binary buffer or a string (as done by SC::ProcessChain::readStdOutUntilEOFSync or other similar methods).

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

Roadmap

🟦 Complete Features:

• None for now

💡 Unplanned Features:

• None for now