A thin and lightweight wrapper around a native file handle. More...

#include <asioext/file_handle.hpp>

Public Types
typedef implementation_defined	native_handle_type
	The operating system's native file handle type. More...

typedef file_handle	lowest_layer_type
	A file_handle is always the lowest layer. More...

Public Member Functions
	file_handle () noexcept
	Construct an empy file_handle. More...

	~file_handle ()

	file_handle (const native_handle_type &handle) noexcept
	Construct a file_handle using a native handle. More...

lowest_layer_type &	lowest_layer () noexcept
	Get a reference to the lowest layer. More...

const lowest_layer_type &	lowest_layer () const noexcept
	Get a const reference to the lowest layer. More...

native_handle_type	native_handle () const noexcept
	Get the native handle representation. More...

Handle-management functions
bool	is_open () const noexcept
	Determine whether the handle is open. More...

void	close ()
	Close the handle. More...

void	close (error_code &ec) noexcept
	Close the handle. More...

void	clear () noexcept
	Clear the handle. More...

Positioning functions
uint64_t	position ()
	Get the current file position. More...

uint64_t	position (error_code &ec) noexcept
	Get the current file position. More...

uint64_t	seek (seek_origin origin, int64_t offset)
	Change the read/write position. More...

uint64_t	seek (seek_origin origin, int64_t offset, error_code &ec) noexcept
	Change the read/write position. More...

Metadata functions
uint64_t	size ()
	Get the size of a file. More...

uint64_t	size (error_code &ec) noexcept
	Get the size of a file. More...

void	size (uint64_t new_size)
	Set the size of a file. More...

void	size (uint64_t new_size, error_code &ec) noexcept
	Set the size of a file. More...

file_perms	permissions ()
	Get the file's current access permissions. More...

file_perms	permissions (error_code &ec) noexcept
	Get the file's current access permissions. More...

void	permissions (file_perms perms, file_perm_options opts=file_perm_options::replace)
	Change file access permissions. More...

void	permissions (file_perms perms, error_code &ec) noexcept
	Change file access permissions. More...

void	permissions (file_perms perms, file_perm_options opts, error_code &ec) noexcept
	Change file access permissions. More...

file_attrs	attributes ()
	Get the file's attributes. More...

file_attrs	attributes (error_code &ec) noexcept
	Get the file's attributes. More...

void	attributes (file_attrs attrs, file_attr_options opts=file_attr_options::replace)
	Change the file's attributes. More...

void	attributes (file_attrs attrs, error_code &ec) noexcept
	Change the file's attributes. More...

void	attributes (file_attrs attrs, file_attr_options opts, error_code &ec) noexcept
	Change the file's attributes. More...

file_times	times ()
	Get the file's time data. More...

file_times	times (error_code &ec) noexcept
	Get the file's time data. More...

void	times (const file_times &new_times)
	Change a file's time data. More...

void	times (const file_times &new_times, error_code &ec) noexcept
	Change a file's time data. More...

SyncReadStream functions
template<typename MutableBufferSequence >
std::size_t	read_some (const MutableBufferSequence &buffers)
	Read some data from the file. More...

template<typename MutableBufferSequence >
std::size_t	read_some (const MutableBufferSequence &buffers, error_code &ec) noexcept
	Read some data from the file. More...

SyncWriteStream functions
template<typename ConstBufferSequence >
std::size_t	write_some (const ConstBufferSequence &buffers)
	Write some data to the file. More...

template<typename ConstBufferSequence >
std::size_t	write_some (const ConstBufferSequence &buffers, error_code &ec) noexcept
	Write some data to the file. More...

SyncRandomAccessReadDevice functions
template<typename MutableBufferSequence >
std::size_t	read_some_at (uint64_t offset, const MutableBufferSequence &buffers)
	Read some data from the file at the specified offset. More...

template<typename MutableBufferSequence >
std::size_t	read_some_at (uint64_t offset, const MutableBufferSequence &buffers, error_code &ec) noexcept
	Read some data from the file at the specified offset. More...

SyncRandomAccessWriteDevice functions
template<typename ConstBufferSequence >
std::size_t	write_some_at (uint64_t offset, const ConstBufferSequence &buffers)
	Write some data to the file at the specified offset. More...

template<typename ConstBufferSequence >
std::size_t	write_some_at (uint64_t offset, const ConstBufferSequence &buffers, error_code &ec) noexcept
	Write some data to the file at the specified offset. More...

Detailed Description

A thin and lightweight wrapper around a native file handle.

The file_handle class provides uniform access to native OS file handles, wrapping the relevant OS APIs in portable methods.

file_handle doesn't assume ownership of the contained handle. If handle management is desired as well, take a look at the unique_file_handle class.

file_handle models the following asio concepts:

SyncRandomAccessReadDevice
SyncRandomAccessWriteDevice
SyncReadStream
SyncWriteStream

Thread Safety:: Distinct objects: Safe.
Shared objects: Unsafe.

Note: This is a low-level component. Most of the time unique_file_handle is a better fit.

Member Typedef Documentation

◆ lowest_layer_type

typedef file_handle asioext::file_handle::lowest_layer_type

A file_handle is always the lowest layer.

◆ native_handle_type

typedef implementation_defined asioext::file_handle::native_handle_type

The operating system's native file handle type.

Constructor & Destructor Documentation

◆ file_handle() [1/2]

asioext::file_handle::file_handle ( )

noexcept

Construct an empy file_handle.

This constructor initializes the file_handle to an empty state.

◆ ~file_handle()

asioext::file_handle::~file_handle ( )

Destroy a file_handle.

This destructor does nothing. Any contained handle will not be closed.

◆ file_handle() [2/2]

asioext::file_handle::file_handle ( const native_handle_type & handle )

noexcept

Construct a file_handle using a native handle.

This constructor doesn't take ownership of the given native file handle.

Parameters

handle The native file handle which shall be assigned to this file_handle object.

Member Function Documentation

◆ attributes() [1/5]

file_attrs asioext::file_handle::attributes ( )

Get the file's attributes.

This function returns the file's attributes as a file_attrs bitmask.

Returns: The file's attributes.

Exceptions

asio::system_error Thrown on failure.

◆ attributes() [2/5]

file_attrs asioext::file_handle::attributes ( error_code & ec )

noexcept

Get the file's attributes.

This function returns the file's attributes as a file_attrs bitmask.

Parameters

ec	Set to indicate what error occurred. If no error occurred, the object is reset.

Returns: The file's attributes.

◆ attributes() [3/5]

void asioext::file_handle::attributes	(	file_attrs	attrs,
		file_attr_options	opts = `file_attr_options::replace`
	)

Change the file's attributes.

This function changes the file's attributes. Depending on whether file_attr_options::add_attrs, file_attr_options::remove_attrs are set, attributes are either added, removed or replaced.

Parameters

attrs	Attributes to set, add or remove.
opts	Options controlling this function's behavior.

Exceptions

asio::system_error Thrown on failure.

◆ attributes() [4/5]

void asioext::file_handle::attributes	(	file_attrs	attrs,
		error_code &	ec
	)

noexcept

Change the file's attributes.

This function changes the file's attributes. Depending on whether file_attr_options::add_attrs, file_attr_options::remove_attrs are set, attributes are either added, removed or replaced.

Parameters

attrs	Attributes to set, add or remove.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

◆ attributes() [5/5]

void asioext::file_handle::attributes	(	file_attrs	attrs,
		file_attr_options	opts,
		error_code &	ec
	)

noexcept

Change the file's attributes.

This function changes the file's attributes. Depending on whether file_attr_options::add_attrs, file_attr_options::remove_attrs are set, attributes are either added, removed or replaced.

Parameters

attrs	Attributes to set, add or remove.
opts	Options controlling this function's behavior.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

◆ clear()

void asioext::file_handle::clear ( )

noexcept

Clear the handle.

This function resets the contained handle to an empty state. The previous handle is not closed.

◆ close() [1/2]

void asioext::file_handle::close ( )

Close the handle.

This function closes the contained handle. Does nothing if the object contains no handle.

Exceptions

asio::system_error Thrown on failure.

◆ close() [2/2]

void asioext::file_handle::close ( error_code & ec )

noexcept

Close the handle.

This function closes the contained handle. Does nothing if the object contains no handle.

Parameters

ec	Set to indicate what error occurred. If no error occurred, the object is reset.

◆ is_open()

bool asioext::file_handle::is_open ( ) const

noexcept

Determine whether the handle is open.

◆ lowest_layer() [1/2]

lowest_layer_type& asioext::file_handle::lowest_layer ( )

inlinenoexcept

Get a reference to the lowest layer.

This function returns a reference to the lowest layer in a stack of layers. Since a file_handle cannot contain any further layers, it simply returns a reference to itself.

Returns: A reference to the lowest layer in the stack of layers. Ownership is not transferred to the caller.

◆ lowest_layer() [2/2]

const lowest_layer_type& asioext::file_handle::lowest_layer ( ) const

inlinenoexcept

Get a const reference to the lowest layer.

This function returns a const reference to the lowest layer in a stack of layers. Since a file_handle cannot contain any further layers, it simply returns a reference to itself.

Returns: A const reference to the lowest layer in the stack of layers. Ownership is not transferred to the caller.

◆ native_handle()

native_handle_type asioext::file_handle::native_handle ( ) const

inlinenoexcept

Get the native handle representation.

This function may be used to obtain the underlying representation of the handle. This is intended to allow access to native handle functionality that is not otherwise provided.

◆ permissions() [1/5]

file_perms asioext::file_handle::permissions ( )

Get the file's current access permissions.

This function returns the file's current access permissions as a file_perms bitmask.

Returns: The file's access permissions.

Exceptions

asio::system_error Thrown on failure.

◆ permissions() [2/5]

file_perms asioext::file_handle::permissions ( error_code & ec )

noexcept

Get the file's current access permissions.

This function returns the file's current access permissions as a file_perms bitmask.

Returns: The file's access permissions.

Parameters

ec	Set to indicate what error occurred. If no error occurred, the object is reset.

◆ permissions() [3/5]

void asioext::file_handle::permissions	(	file_perms	perms,
		file_perm_options	opts = `file_perm_options::replace`
	)

Change file access permissions.

This function changes the file's access permissions. Depending on whether file_perm_options::add_perms, file_perm_options::remove_perms are set, permissions are either added, removed or replaced.

Parameters

perms	Permissions to set, add or remove.
opts	Options controlling this function's behavior.

Exceptions

asio::system_error Thrown on failure.

◆ permissions() [4/5]

void asioext::file_handle::permissions	(	file_perms	perms,
		error_code &	ec
	)

noexcept

Change file access permissions.

This function changes the file's access permissions. Depending on whether file_perm_options::add_perms, file_perm_options::remove_perms are set, permissions are either added, removed or replaced.

Parameters

perms	Permissions to set, add or remove.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

◆ permissions() [5/5]

void asioext::file_handle::permissions	(	file_perms	perms,
		file_perm_options	opts,
		error_code &	ec
	)

noexcept

Change file access permissions.

This function changes the file's access permissions. Depending on whether file_perm_options::add_perms, file_perm_options::remove_perms are set, permissions are either added, removed or replaced.

Parameters

perms	Permissions to set, add or remove.
opts	Options controlling this function's behavior.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

◆ position() [1/2]

uint64_t asioext::file_handle::position ( )

Get the current file position.

This function retrieves the current read/write position of this file handle, relative to the file's beginning.

Returns: The current absolute file position.

Exceptions

asio::system_error Thrown on failure.

◆ position() [2/2]

uint64_t asioext::file_handle::position ( error_code & ec )

noexcept

Get the current file position.

This function retrieves the current read/write position of this file handle, relative to the file's beginning.

Returns: The current absolute file position.

Parameters

ec	Set to indicate what error occurred. If no error occurred, the object is reset.

◆ read_some() [1/2]

template<typename MutableBufferSequence >

std::size_t asioext::file_handle::read_some ( const MutableBufferSequence & buffers )

Read some data from the file.

This function is used to read data from the file, starting at the file_handle's current file position. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

Parameters

buffers One or more buffers into which the data will be read.

Returns: The number of bytes read.

Exceptions

asio::system_error Thrown on failure. An error code of asio::error::eof indicates that the end of file was reached.

Note: The read_some operation may not read all of the requested number of bytes. Consider using the asio::read function if you need to ensure that the requested amount of data is read before the blocking operation completes.

Example: To read into a single data buffer use the asio::buffer function as follows:
fh.read_some(asio::buffer(data, size));
See the asio::buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

◆ read_some() [2/2]

template<typename MutableBufferSequence >

std::size_t asioext::file_handle::read_some	(	const MutableBufferSequence &	buffers,
		error_code &	ec
	)

noexcept

Read some data from the file.

This function is used to read data from the file, starting at the file_handle's current file position. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

Parameters

buffers	One or more buffers into which the data will be read.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

Returns: The number of bytes read. Returns 0 if an error occurred.

Note: The read_some operation may not read all of the requested number of bytes. Consider using the asio::read function if you need to ensure that the requested amount of data is read before the blocking operation completes.

◆ read_some_at() [1/2]

template<typename MutableBufferSequence >

std::size_t asioext::file_handle::read_some_at	(	uint64_t	offset,
		const MutableBufferSequence &	buffers
	)

Read some data from the file at the specified offset.

This function is used to read data from the file. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

Parameters

offset	The offset at which the data will be read, relative to the file's beginning.
buffers	One or more buffers into which the data will be read.

Returns: The number of bytes read.

Exceptions

asio::system_error Thrown on failure. An error code of asio::error::eof indicates that the end of the file was reached.

Note: The read_some operation may not read all of the requested number of bytes. Consider using the asio::read_at function if you need to ensure that the requested amount of data is read before the blocking operation completes.

Example: To read into a single data buffer use the asio::buffer function as follows:
handle.read_some_at(42, asio::buffer(data, size));
See the asio::buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

◆ read_some_at() [2/2]

template<typename MutableBufferSequence >

std::size_t asioext::file_handle::read_some_at	(	uint64_t	offset,
		const MutableBufferSequence &	buffers,
		error_code &	ec
	)

noexcept

Read some data from the file at the specified offset.

This function is used to read data from the file. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

Parameters

offset	The offset at which the data will be read, relative to the file's beginning.
buffers	One or more buffers into which the data will be read.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

Returns: The number of bytes read. Returns 0 if an error occurred.

Note: The read_some operation may not read all of the requested number of bytes. Consider using the asio::read_at function if you need to ensure that the requested amount of data is read before the blocking operation completes.

◆ seek() [1/2]

uint64_t asioext::file_handle::seek	(	seek_origin	origin,
		int64_t	offset
	)

Change the read/write position.

This function repositions the current read/write position of this file_handle by offset, relative to the origin specified by origin.

Parameters

origin	The origin of `offset`.
offset	The offset by which the current position's modified.

Returns: The new absolute file position.

Exceptions

asio::system_error Thrown on failure.

◆ seek() [2/2]

uint64_t asioext::file_handle::seek	(	seek_origin	origin,
		int64_t	offset,
		error_code &	ec
	)

noexcept

Change the read/write position.

This function repositions the current read/write position of this file_handle by offset, relative to the origin specified by origin.

Parameters

origin	The origin of `offset`.
offset	The offset by which the current position's modified.

Returns: The new absolute file position.

Parameters

ec	Set to indicate what error occurred. If no error occurred, the object is reset.

◆ size() [1/4]

uint64_t asioext::file_handle::size ( )

Get the size of a file.

This function retrieves the size of a file, in bytes.

Returns: The total number of bytes in this file.

Exceptions

asio::system_error Thrown on failure.

◆ size() [2/4]

uint64_t asioext::file_handle::size ( error_code & ec )

noexcept

Get the size of a file.

This function retrieves the size of a file, in bytes.

Returns: The total number of bytes in this file.

Parameters

ec	Set to indicate what error occurred. If no error occurred, the object is reset.

◆ size() [3/4]

void asioext::file_handle::size ( uint64_t new_size )

Set the size of a file.

This function resizes the file so its new size matches new_size.

Parameters

new_size The new total size of the file (in bytes).

Exceptions

asio::system_error Thrown on failure.

◆ size() [4/4]

void asioext::file_handle::size	(	uint64_t	new_size,
		error_code &	ec
	)

noexcept

Set the size of a file.

This function resizes the file so its new size matches new_size.

Parameters

new_size	The new total size of the file (in bytes).
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

◆ times() [1/4]

file_times asioext::file_handle::times ( )

Get the file's time data.

This function retrieves the various times associated with a file and copies them into a file_times structure.

Times in the file_times struct that are not available for this file are zero-initialized.

Returns: The file's time data.

Exceptions

asio::system_error Thrown on failure.

◆ times() [2/4]

file_times asioext::file_handle::times ( error_code & ec )

noexcept

Get the file's time data.

This function retrieves the various times associated with a file and copies them into a file_times structure.

Times in the file_times struct that are not available for this file are zero-initialized.

Parameters

ec	Set to indicate what error occurred. If no error occurred, the object is reset.

Returns: The file's time data.

◆ times() [3/4]

void asioext::file_handle::times ( const file_times & new_times )

Change a file's time data.

This function replaces a file's time data with the given values. File times that are set to zero inside the file_times structure remain unchanged.

Parameters

new_times The new file times. Zero values are ignored.

Exceptions

asio::system_error Thrown on failure.

◆ times() [4/4]

void asioext::file_handle::times	(	const file_times &	new_times,
		error_code &	ec
	)

noexcept

Change a file's time data.

This function replaces a file's time data with the given values. File times that are set to zero inside the file_times structure remain unchanged.

Parameters

new_times	The new file times. Zero values are ignored.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

◆ write_some() [1/2]

template<typename ConstBufferSequence >

std::size_t asioext::file_handle::write_some ( const ConstBufferSequence & buffers )

Write some data to the file.

This function is used to write data to the file, starting at the file_handle's current file position. The function call will block until one or more bytes of the data has been written successfully, or until an error occurs.

Parameters

buffers One or more data buffers to be written to the file.

Returns: The number of bytes written.

Exceptions

asio::system_error Thrown on failure.

Note: The write_some operation may not transmit all of the data to the peer. Consider using the asio::write function if you need to ensure that all data is written before the blocking operation completes.

Example: To write a single data buffer use the asio::buffer function as follows:
fh.write_some(asio::buffer(data, size));
See the asio::buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

◆ write_some() [2/2]

template<typename ConstBufferSequence >

std::size_t asioext::file_handle::write_some	(	const ConstBufferSequence &	buffers,
		error_code &	ec
	)

noexcept

Write some data to the file.

This function is used to write data to the file, starting at the file_handle's current file position. The function call will block until one or more bytes of the data has been written successfully, or until an error occurs.

Parameters

buffers	One or more data buffers to be written to the file.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

Returns: The number of bytes written. Returns 0 if an error occurred.

Note: The write_some operation may not transmit all of the data to the peer. Consider using the asio::write function if you need to ensure that all data is written before the blocking operation completes.

◆ write_some_at() [1/2]

template<typename ConstBufferSequence >

std::size_t asioext::file_handle::write_some_at	(	uint64_t	offset,
		const ConstBufferSequence &	buffers
	)

Write some data to the file at the specified offset.

This function is used to write data to the file. The function call will block until one or more bytes of the data has been written successfully, or until an error occurs.

Parameters

offset	The offset at which the data will be written, relative to the file's beginning.
buffers	One or more data buffers to be written.

Returns: The number of bytes written.

Exceptions

asio::system_error Thrown on failure.

Note: The write_some_at operation may not write all of the data. Consider using the asio::write_at function if you need to ensure that all data is written before the blocking operation completes.

Example: To write a single data buffer use the asio::buffer function as follows:
fh.write_some_at(42, asio::buffer(data, size));
See the asio::buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

◆ write_some_at() [2/2]

template<typename ConstBufferSequence >

std::size_t asioext::file_handle::write_some_at	(	uint64_t	offset,
		const ConstBufferSequence &	buffers,
		error_code &	ec
	)

noexcept

Write some data to the file at the specified offset.

This function is used to write data to the file. The function call will block until one or more bytes of the data has been written successfully, or until an error occurs.

Parameters

offset	The offset at which the data will be written, relative to the file's beginning.
buffers	One or more data buffers to be written to the handle.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

Returns: The number of bytes written. Returns 0 if an error occurred.

Note: The write_some_at operation may not write all of the data. Consider using the asio::write_at function if you need to ensure that all data is written before the blocking operation completes.

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ lowest_layer_type

◆ native_handle_type

Constructor & Destructor Documentation

◆ file_handle() [1/2]

◆ ~file_handle()

◆ file_handle() [2/2]

Member Function Documentation

◆ attributes() [1/5]

◆ attributes() [2/5]

◆ attributes() [3/5]

◆ attributes() [4/5]

◆ attributes() [5/5]

◆ clear()

◆ close() [1/2]

◆ close() [2/2]

◆ is_open()

◆ lowest_layer() [1/2]

◆ lowest_layer() [2/2]

◆ native_handle()

◆ permissions() [1/5]

◆ permissions() [2/5]

◆ permissions() [3/5]

◆ permissions() [4/5]

◆ permissions() [5/5]

◆ position() [1/2]

◆ position() [2/2]

◆ read_some() [1/2]

◆ read_some() [2/2]

◆ read_some_at() [1/2]

◆ read_some_at() [2/2]

◆ seek() [1/2]

◆ seek() [2/2]

◆ size() [1/4]

◆ size() [2/4]

◆ size() [3/4]

◆ size() [4/4]

◆ times() [1/4]

◆ times() [2/4]

◆ times() [3/4]

◆ times() [4/4]

◆ write_some() [1/2]

◆ write_some() [2/2]

◆ write_some_at() [1/2]

◆ write_some_at() [2/2]