SC::FileDescriptor Struct Reference

[UniqueHandleDeclaration2Snippet] More...

#include <File.h>

Inheritance diagram for SC::FileDescriptor:

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

Public Member Functions
ResultFile	openForWriteToDevNull ()
	... [UniqueHandleDeclaration2Snippet]
ResultFile	openStdOutDuplicate ()
	Opens a duplicated file descriptor handle for reading from stdout.
ResultFile	openStdErrDuplicate ()
	Opens a duplicated file descriptor handle for reading from stderr.
ResultFile	openStdInDuplicate ()
	Opens a duplicated file descriptor handle for reading from stdin.
ResultFile	open (StringSpan path, FileOpen mode)
	Opens a file descriptor handle from a file system path.
ResultFile	read (Span< char > data, Span< char > &actuallyRead, uint64_t offset)
	Reads bytes at offset into user supplied span.
ResultFile	read (Span< uint8_t > data, Span< uint8_t > &actuallyRead, uint64_t offset)
	Reads bytes at offset into user supplied span.
ResultFile	read (Span< char > data, Span< char > &actuallyRead)
	Reads bytes from current position (FileDescriptor::seek) into user supplied Span.
ResultFile	readUntilFullOrEOF (Span< char > data, Span< char > &actuallyRead)
	Reads bytes from current position (FileDescriptor::seek) into Span, until full or EOF is reached.
ResultFile	read (Span< uint8_t > data, Span< uint8_t > &actuallyRead)
	Reads bytes from current position (FileDescriptor::seek) into user supplied Span.
template<typename T >
ResultFile	readUntilEOF (T &destination)
	Reads into a given dynamic buffer until End of File (EOF) is signaled.
ResultFile	readUntilEOF (IGrowableBuffer &&buffer)
	Reads into a given dynamic buffer until End of File (EOF) is signaled.
ResultFile	writeString (StringSpan data)
	Writes a string to the file descriptor.
ResultFile	write (Span< const char > data, uint64_t offset)
	Writes bytes at offset from start of the file descriptor.
ResultFile	write (Span< const uint8_t > data, uint64_t offset)
	Writes bytes at offset from start of the file descriptor.
ResultFile	write (Span< const char > data)
	Writes bytes from current position (FileDescriptor::seek) of the file descriptor.
ResultFile	write (Span< const uint8_t > data)
	Writes bytes from current position (FileDescriptor::seek) of the file descriptor.
ResultFile	seek (SeekMode seekMode, int64_t offset)
	Changes the current position in the file descriptor, if seekable.
ResultFile	currentPosition (size_t &position) const
	Gets current descriptor position (if seekable)
ResultFile	sizeInBytes (size_t &sizeInBytes) const
	Gets total file size in bytes (if seekable)
ResultFile	stat (FileDescriptorStat &fileStat) const
	Obtains richer metadata associated with the currently open descriptor.
ResultFile	chmod (uint32_t mode)
	Change file permission bits for the currently open descriptor.
ResultFile	chown (uint32_t uid, uint32_t gid)
	Change owner and group for the currently open descriptor.
ResultFile	sync ()
	Flush file data and metadata to stable storage.
ResultFile	syncData ()
	Flush file data to stable storage.
ResultFile	truncate (uint64_t sizeInBytes)
	Resize the underlying file to the specified size in bytes.

Friends
struct	File
struct	PipeDescriptor

Detailed Description

[UniqueHandleDeclaration2Snippet]

Open, read and write to/from a file descriptor (like a file or pipe).

Member Enumeration Documentation

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

chmod()

ResultFile SC::FileDescriptor::chmod

(

uint32_t

mode

)

Change file permission bits for the currently open descriptor.

Parameters

mode	Platform-native numeric mode bits

Returns

Valid result if permissions were updated successfully

chown()

ResultFile SC::FileDescriptor::chown	(	uint32_t	uid,
		uint32_t	gid )

Change owner and group for the currently open descriptor.

Parameters

uid	Platform-native numeric owner identifier
gid	Platform-native numeric group identifier

Returns

Valid result if ownership was updated successfully

currentPosition()

ResultFile 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

open()

ResultFile SC::FileDescriptor::open	(	StringSpan	path,
		FileOpen	mode )

Opens a file descriptor handle from a file system path.

Parameters

path	The absolute path to file. It MUST be encoded in ASCII,UTF-8/16 on Windows, ASCII,UTF-8 on POSIX.
mode	The mode used to open file (read-only, write-append etc.)

Returns

Valid Result if file is opened successfully

openForWriteToDevNull()

ResultFile SC::FileDescriptor::openForWriteToDevNull

(

)

... [UniqueHandleDeclaration2Snippet]

Opens a file descriptor handle for writing to /dev/null or equivalent on current OS.

Returns

true if file has been opened successfully

openStdErrDuplicate()

ResultFile SC::FileDescriptor::openStdErrDuplicate

(

)

Opens a duplicated file descriptor handle for reading from stderr.

Note

The returned handle CAN be closed because it will be a duplicate of the original handle.

openStdInDuplicate()

ResultFile SC::FileDescriptor::openStdInDuplicate

(

)

Opens a duplicated file descriptor handle for reading from stdin.

Note

The returned handle CAN be closed because it will be a duplicate of the original handle.

openStdOutDuplicate()

ResultFile SC::FileDescriptor::openStdOutDuplicate

(

)

Opens a duplicated file descriptor handle for reading from stdout.

Note

The returned handle CAN be closed because it will be a duplicate of the original handle.

read() [1/4]

ResultFile 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]

ResultFile 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]

ResultFile 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]

ResultFile 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/2]

ResultFile SC::FileDescriptor::readUntilEOF

(

IGrowableBuffer &&

buffer

)

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

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

Parameters

buffer

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

Returns

Valid result if read succeeded until EOF

readUntilEOF() [2/2]

template<typename T >

ResultFile SC::FileDescriptor::readUntilEOF ( T & destination )

inline

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

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

Template Parameters

T	Type of the destination buffer implementing IGrowableBuffer interface (String, SmallString, Buffer)

Parameters

destination

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

Returns

Valid result if read succeeded until EOF

readUntilFullOrEOF()

ResultFile SC::FileDescriptor::readUntilFullOrEOF	(	Span< char >	data,
		Span< char > &	actuallyRead )

Reads bytes from current position (FileDescriptor::seek) into Span, until full or EOF is reached.

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

seek()

ResultFile SC::FileDescriptor::seek	(	SeekMode	seekMode,
		int64_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 (can be negative)

Returns

Valid result if seek succeeds

sizeInBytes()

ResultFile 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

stat()

ResultFile SC::FileDescriptor::stat

(

FileDescriptorStat &

fileStat

)

const

Obtains richer metadata associated with the currently open descriptor.

Parameters

[out]

fileStat

Destination structure receiving descriptor metadata

Returns

Valid result if metadata was read successfully

sync()

ResultFile SC::FileDescriptor::sync

(

)

Flush file data and metadata to stable storage.

Returns

Valid result if synchronization succeeded

syncData()

ResultFile SC::FileDescriptor::syncData

(

)

Flush file data to stable storage.

Returns

Valid result if synchronization succeeded

truncate()

ResultFile SC::FileDescriptor::truncate

(

uint64_t

sizeInBytes

)

Resize the underlying file to the specified size in bytes.

Parameters

sizeInBytes

New desired file size

Returns

Valid result if truncation succeeded

write() [1/4]

ResultFile 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]

ResultFile 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]

ResultFile 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]

ResultFile 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

writeString()

ResultFile SC::FileDescriptor::writeString

(

StringSpan

data

)

Writes a string to the file descriptor.

Parameters

data	The string data to write

Returns

Valid result if write succeeded

---

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

• File.h