arene::base::filesystem::file_handle Class Reference

An RAII wrapper around a POSIX file handle with unique-ownership semantics. More...

Public Member Functions
	file_handle () noexcept
	Default construct with an invalid value.
	file_handle (file_handle &&other) noexcept
	Transfer ownership of the handle from other to *this.
	file_handle (file_handle const &)=delete
	Not copyable.
	file_handle (os_file_handle const file_descriptor) noexcept
	Take ownership of the specified handle.
	~file_handle ()
	Close the handle if there is one.
auto	close () noexcept -> result< void, error_code >
	Close the file handle, if there is one.
auto	flush () const noexcept -> result< void, error_code >
	Flush the file handle.
auto	get_fd () const noexcept -> os_file_handle
	Get the wrapped handle.
auto	operator= (file_handle &&other) noexcept -> file_handle &
	Take ownership of the file handle from other.
auto	operator= (file_handle const &) -> file_handle &=delete
	Not copyable.
auto	read_at (span< byte > buffer, std::uint64_t const position) const noexcept -> result< span< byte >, error_code >
	Read from the file handle, starting at the specified position, into the provided buffer.
void	release () noexcept
	Release ownership of the handle, if held.
auto	sequential_read (span< byte > buffer) const noexcept -> result< span< byte >, error_code >
	Read from the file handle, starting at the current sequential access position, into the provided buffer. Updates the sequential access position to the end of the read data.
auto	sequential_seek (std::uint64_t const position) const noexcept -> result< void, error_code >
	Move the sequential access position to the specified offset from the start of the file.
auto	sequential_write (span< byte const > data) const noexcept -> result< span< byte const >, error_code >
	Write data from the provided buffer to the file referenced by the handle, starting at the current sequential access position. Updates the sequential access position to the end of the written data.
auto	size () const noexcept -> result< std::uint64_t, error_code >
	Get the size of the open file.
auto	valid () const noexcept -> bool
	Check if the handle currently holds a file descriptor.
auto	write_at (span< byte const > data, std::uint64_t const position) const noexcept -> result< span< byte const >, error_code >
	Write data from the provided buffer to the file referenced by the handle, starting at the specified position in the file.

Static Public Attributes
static constexpr os_file_handle	invalid_handle_value {-1}
	An invalid handle value.

Detailed Description

An RAII wrapper around a POSIX file handle with unique-ownership semantics.

Constructor & Destructor Documentation

file_handle() [1/4]

arene::base::filesystem::file_handle::file_handle ( )

inlinenoexcept

Default construct with an invalid value.

Postcondition

get_fd() == invalid_handle_value

file_handle() [2/4]

arene::base::filesystem::file_handle::file_handle ( os_file_handle const file_descriptor )

inlineexplicitnoexcept

Take ownership of the specified handle.

Parameters

file_descriptor

The file handle to own

Postcondition

get_fd() == file_description

~file_handle()

arene::base::filesystem::file_handle::~file_handle

(

)

Close the handle if there is one.

Postcondition

If valid() == true , the file descriptor will be closed using underlying OS mechanisms.

file_handle() [3/4]

arene::base::filesystem::file_handle::file_handle ( file_handle && other )

inlinenoexcept

Transfer ownership of the handle from other to *this.

Parameters

other

the other file_handle to take ownership from

file_handle() [4/4]

arene::base::filesystem::file_handle::file_handle ( file_handle const & )

delete

Not copyable.

Member Function Documentation

close()

auto arene::base::filesystem::file_handle::close ( ) -> result<void, error_code>

noexcept

Close the file handle, if there is one.

Returns

result<void, error_code> A result that is either:

• An empty value for success.
• An error_code indicating the reason for failure if the handle could not be closed.

flush()

auto arene::base::filesystem::file_handle::flush ( ) const -> result<void, error_code>

noexcept

Flush the file handle.

Returns

result<void, error_code> A result that is either:

• An empty value for success
• An error_code indicating the reason for failure if the flush failed.

get_fd()

auto arene::base::filesystem::file_handle::get_fd ( ) const -> os_file_handle

inlinenoexcept

Get the wrapped handle.

Returns

the handle value.

operator=() [1/2]

auto arene::base::filesystem::file_handle::operator= ( file_handle && other ) -> file_handle&

inlinenoexcept

Take ownership of the file handle from other.

Parameters

other

the other file_handle to take ownership from

Returns

*this

Postcondition

If *this held a file handle before assignment, it is closed.

get_fd() will return the value previously held by other

operator=() [2/2]

auto arene::base::filesystem::file_handle::operator= ( file_handle const & ) -> file_handle &=delete

delete

Not copyable.

read_at()

auto arene::base::filesystem::file_handle::read_at ( span< byte > buffer, std::uint64_t const position ) const -> result<span<byte>, error_code>

noexcept

Read from the file handle, starting at the specified position, into the provided buffer.

Parameters

buffer	A view onto a buffer to write the read bytes into into. The read will never be larger then the provided span.
position	The position in the file to read from

Returns

result<span<const byte>, error_code> A result holding either:

• A sub-span of buffer that is a view onto to the actual data read.
• An error_code indicating the reason for failure to read.

release()

void arene::base::filesystem::file_handle::release ( )

inlinenoexcept

Release ownership of the handle, if held.

Postcondition

get_fd() == invalid_handle_value .

sequential_read()

auto arene::base::filesystem::file_handle::sequential_read ( span< byte > buffer ) const -> result<span<byte>, error_code>

noexcept

Read from the file handle, starting at the current sequential access position, into the provided buffer. Updates the sequential access position to the end of the read data.

Parameters

buffer

The buffer to read into. The read will never be larger then the provided buffer.

Returns

result<span<byte>, error_code> A result holding either:

• A sub-span of buffer that is a view onto to the actual data read.
• An error_code indicating the reason for failure to read.

sequential_seek()

auto arene::base::filesystem::file_handle::sequential_seek ( std::uint64_t const position ) const -> result<void, error_code>

noexcept

Move the sequential access position to the specified offset from the start of the file.

Parameters

position

The position in the file to use for subsequent sequential access

Returns

result<void, error_code> A result that is either:

• An empty value for success
• An error_code indicating the reason for failure if the seek failed.

sequential_write()

auto arene::base::filesystem::file_handle::sequential_write ( span< byte const > data ) const -> result<span<byte const>, error_code>

noexcept

Write data from the provided buffer to the file referenced by the handle, starting at the current sequential access position. Updates the sequential access position to the end of the written data.

Parameters

data	The data to write

Returns

result<span<const byte>, error_code> A result holding either:

• A sub-span of data that refers to the remaining unwritten data for a successful write, if any. If all data was written, this span will be empty.
• An error_code indicating the reason for failure to write.

size()

auto arene::base::filesystem::file_handle::size ( ) const -> result<std::uint64_t, error_code>

noexcept

Get the size of the open file.

Returns

A result holding the file size on success, or an error_code indicating the reason for failure.

valid()

auto arene::base::filesystem::file_handle::valid ( ) const -> bool

inlinenoexcept

Check if the handle currently holds a file descriptor.

Returns

true if get_fd() != invalid_handle_value .

false otherwise.

write_at()

auto arene::base::filesystem::file_handle::write_at ( span< byte const > data, std::uint64_t const position ) const -> result<span<byte const>, error_code>

noexcept

Write data from the provided buffer to the file referenced by the handle, starting at the specified position in the file.

Parameters

data	The data to write
position	The position in the file to write at

Returns

result<span<const byte>, error_code> A result holding either:

• A sub-span of data that refers to the remaining unwritten data for a successful write, if any. If all data was written, this span will be empty.
• An error_code indicating the reason for failure to write.

Member Data Documentation

invalid_handle_value

file_handle::os_file_handle arene::base::filesystem::file_handle::invalid_handle_value {-1}

staticconstexpr

An invalid handle value.

---

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

• arene/base/filesystem/file_handle.hpp
• arene/base/filesystem/file_handle.cpp