Basic interface for (a)synchronous file I/O. More...

#include <asioext/basic_file.hpp>

Inheritance diagram for asioext::basic_file< FileService >:

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

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

Public Member Functions
	basic_file (asio::io_service &io_service) noexcept
	Construct an unopened file. More...

	basic_file (asio::io_service &io_service, const file_handle &handle) noexcept
	Construct a file using a native handle object. More...

	basic_file (asio::io_service &io_service, const native_handle_type &handle) noexcept
	Construct a file using a native handle object. More...

	basic_file (asio::io_service &io_service, const char *filename, open_flags flags, file_perms perms=file_perms::create_default, file_attrs attrs=file_attrs::none)
	Open a file and construct a basic_file. More...

	basic_file (asio::io_service &io_service, const char *filename, open_flags flags, file_perms perms, file_attrs attrs, error_code &ec) noexcept
	Open a file and construct a basic_file. More...

	basic_file (asio::io_service &io_service, const wchar_t *filename, open_flags flags, file_perms perms=file_perms::create_default, file_attrs attrs=file_attrs::none)
	Open a file and construct a basic_file. More...

	basic_file (asio::io_service &io_service, const wchar_t *filename, open_flags flags, file_perms perms, file_attrs attrs, error_code &ec) noexcept
	Open a file and construct a basic_file. More...

	basic_file (asio::io_service &io_service, const boost::filesystem::path &filename, open_flags flags, file_perms perms=file_perms::create_default, file_attrs attrs=file_attrs::none)
	Open a file and construct a basic_file. More...

	basic_file (asio::io_service &io_service, const boost::filesystem::path &filename, open_flags flags, file_perms perms, file_attrs attrs, error_code &ec) noexcept
	Open a file and construct a basic_file. 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 () noexcept
	Get the native handle representation. More...

void	cancel ()
	Cancel all asynchronous operations associated with the file. More...

void	cancel (error_code &ec) noexcept
	Cancel all asynchronous operations associated with the file. More...

Handle-management functions
void	open (const char *filename, open_flags flags, file_perms perms=file_perms::create_default, file_attrs attrs=file_attrs::none)
	Open a file. More...

void	open (const char *filename, open_flags flags, file_perms perms, file_attrs attrs, error_code &ec) noexcept
	Open a file. More...

void	open (const wchar_t *filename, open_flags flags, file_perms perms=file_perms::create_default, file_attrs attrs=file_attrs::none)
	Open a file. More...

void	open (const wchar_t *filename, open_flags flags, file_perms perms, file_attrs attrs, error_code &ec) noexcept
	Open a file. More...

void	open (const boost::filesystem::path &filename, open_flags flags, file_perms perms=file_perms::create_default, file_attrs attrs=file_attrs::none)
	Open a file. More...

void	open (const boost::filesystem::path &filename, open_flags flags, file_perms perms, file_attrs attrs, error_code &ec) noexcept
	Open a file. More...

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...

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...

AsyncReadStream functions
template<typename MutableBufferSequence , typename ReadHandler >
void_or_deduced	async_read_some (const MutableBufferSequence &buffers, ReadHandler &&handler)

AsyncWriteStream functions
template<typename ConstBufferSequence , typename WriteHandler >
void_or_deduced	async_write_some (const ConstBufferSequence &buffers, WriteHandler &&handler)
	Start an asynchronous write. More...

AsyncRandomAccessReadDevice functions
template<typename MutableBufferSequence , typename ReadHandler >
void_or_deduced	async_read_some_at (uint64_t offset, const MutableBufferSequence &buffers, ReadHandler &&handler)
	Start an asynchronous read at the specified offset. More...

AsyncRandomAccessWriteDevice functions
template<typename ConstBufferSequence , typename WriteHandler >
void_or_deduced	async_write_some_at (uint64_t offset, const ConstBufferSequence &buffers, WriteHandler &&handler)
	Start an asynchronous write at the specified offset. More...

Detailed Description

template<class FileService>
class asioext::basic_file< FileService >

Basic interface for (a)synchronous file I/O.

This class template provides a generic interface for (a)synchronous file I/O.

basic_file models the following asio concepts:

SyncRandomAccessReadDevice
SyncRandomAccessWriteDevice
SyncReadStream
SyncWriteStream
AsyncReadStream
AsyncWriteStream
AsyncRandomAccessReadDevice
AsyncRandomAccessWriteDevice

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

Member Typedef Documentation

◆ lowest_layer_type

template<class FileService >

typedef basic_file asioext::basic_file< FileService >::lowest_layer_type

A basic_file is always the lowest layer.

◆ native_handle_type

template<class FileService >

typedef FileService::native_handle_type asioext::basic_file< FileService >::native_handle_type

The operating system's native file handle type.

Constructor & Destructor Documentation

◆ basic_file() [1/9]

template<class FileService >

asioext::basic_file< FileService >::basic_file ( asio::io_service & io_service )

inlineexplicitnoexcept

Construct an unopened file.

Parameters

io_service The io_service object that the file will use to dispatch handlers for any asynchronous operations performed on it.

◆ basic_file() [2/9]

template<class FileService >

asioext::basic_file< FileService >::basic_file	(	asio::io_service &	io_service,
		const file_handle &	handle
	)

inlinenoexcept

Construct a file using a native handle object.

This constructor takes ownership of the given wrapped native handle.

Parameters

io_service	The io_service object that the file will use to dispatch handlers for any asynchronous operations performed on it.
handle	The native handle object, wrapped in a file_handle, which shall be assigned to this basic_file object.

◆ basic_file() [3/9]

template<class FileService >

asioext::basic_file< FileService >::basic_file	(	asio::io_service &	io_service,
		const native_handle_type &	handle
	)

inlinenoexcept

Construct a file using a native handle object.

This constructor takes ownership of the given native handle.

Parameters

io_service	The io_service object that the file will use to dispatch handlers for any asynchronous operations performed on it.
handle	The native handle object which shall be assigned to this basic_file object.

◆ basic_file() [4/9]

template<class FileService >

asioext::basic_file< FileService >::basic_file	(	asio::io_service &	io_service,
		const char *	filename,
		open_flags	flags,
		file_perms	perms = `file_perms::create_default`,
		file_attrs	attrs = `file_attrs::none`
	)

inline

Open a file and construct a basic_file.

This constructor opens a new handle to the given file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

io_service	The io_service object that the file will use to dispatch handlers for any asynchronous operations performed on it.
filename	The path of the file to open.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.

Exceptions

asio::system_error Thrown on failure.

See also: open_flags

◆ basic_file() [5/9]

template<class FileService >

asioext::basic_file< FileService >::basic_file	(	asio::io_service &	io_service,
		const char *	filename,
		open_flags	flags,
		file_perms	perms,
		file_attrs	attrs,
		error_code &	ec
	)

inlinenoexcept

Open a file and construct a basic_file.

This constructor opens a new handle to the given file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

io_service	The io_service object that the file will use to dispatch handlers for any asynchronous operations performed on it.
filename	The path of the file to open.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

See also: open_flags

◆ basic_file() [6/9]

template<class FileService >

asioext::basic_file< FileService >::basic_file	(	asio::io_service &	io_service,
		const wchar_t *	filename,
		open_flags	flags,
		file_perms	perms = `file_perms::create_default`,
		file_attrs	attrs = `file_attrs::none`
	)

inline

Open a file and construct a basic_file.

This constructor opens a new handle to the given file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

io_service	The io_service object that the file will use to dispatch handlers for any asynchronous operations performed on it.
filename	The path of the file to open.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.

Exceptions

asio::system_error Thrown on failure.

See also: open_flags

Note: Only available on Windows.

◆ basic_file() [7/9]

template<class FileService >

asioext::basic_file< FileService >::basic_file	(	asio::io_service &	io_service,
		const wchar_t *	filename,
		open_flags	flags,
		file_perms	perms,
		file_attrs	attrs,
		error_code &	ec
	)

inlinenoexcept

Open a file and construct a basic_file.

This constructor opens a new handle to the given file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

io_service	The io_service object that the file will use to dispatch handlers for any asynchronous operations performed on it.
filename	The path of the file to open.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

See also: open_flags

Note: Only available on Windows.

◆ basic_file() [8/9]

template<class FileService >

asioext::basic_file< FileService >::basic_file	(	asio::io_service &	io_service,
		const boost::filesystem::path &	filename,
		open_flags	flags,
		file_perms	perms = `file_perms::create_default`,
		file_attrs	attrs = `file_attrs::none`
	)

inline

Open a file and construct a basic_file.

This constructor opens a new handle to the given file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

io_service	The io_service object that the file will use to dispatch handlers for any asynchronous operations performed on it.
filename	The path of the file to open.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.

Exceptions

asio::system_error Thrown on failure.

See also: open_flags

◆ basic_file() [9/9]

template<class FileService >

asioext::basic_file< FileService >::basic_file	(	asio::io_service &	io_service,
		const boost::filesystem::path &	filename,
		open_flags	flags,
		file_perms	perms,
		file_attrs	attrs,
		error_code &	ec
	)

inlinenoexcept

Open a file and construct a basic_file.

This constructor opens a new handle to the given file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

io_service	The io_service object that the file will use to dispatch handlers for any asynchronous operations performed on it.
filename	The path of the file to open.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

See also: open_flags

Member Function Documentation

◆ async_read_some()

template<class FileService >

template<typename MutableBufferSequence , typename ReadHandler >

void_or_deduced asioext::basic_file< FileService >::async_read_some	(	const MutableBufferSequence &	buffers,
		ReadHandler &&	handler
	)

inline

Start an asynchronous read.

This function is used to asynchronously read data from the file. The function call always returns immediately.

Parameters

buffers One or more buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

handler

The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

 void handler(
  const error_code& error, // Result of operation.
  std::size_t bytes_transferred // Number of bytes read.
); 

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using asio::io_service::post().

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

Example: To read into a single data buffer use the asio::buffer function as follows:
file.async_read_some(asio::buffer(data, size), handler);
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.

Warning: Interleaving asynchronous reads with other operations that cause the file position/pointer to change is undefined!

Note: Starting multiple asynchronous reads is implementation-defined and not recommended. (A FileService might make additional gurantees, but is not required to.)

◆ async_read_some_at()

template<class FileService >

template<typename MutableBufferSequence , typename ReadHandler >

void_or_deduced asioext::basic_file< FileService >::async_read_some_at	(	uint64_t	offset,
		const MutableBufferSequence &	buffers,
		ReadHandler &&	handler
	)

inline

Start an asynchronous read at the specified offset.

This function is used to asynchronously read data from the file. The function call always returns immediately.

Parameters

offset	The offset at which the data will be read.
buffers	One or more buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.
handler	The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: void handler( const error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes read. ); Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using asio::io_service::post().

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

Example: To read into a single data buffer use the asio::buffer function as follows:
file.async_read_some_at(42, asio::buffer(data, size), handler);
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.

◆ async_write_some()

template<class FileService >

template<typename ConstBufferSequence , typename WriteHandler >

void_or_deduced asioext::basic_file< FileService >::async_write_some	(	const ConstBufferSequence &	buffers,
		WriteHandler &&	handler
	)

inline

Start an asynchronous write.

This function is used to asynchronously write data to the file. The function call always returns immediately.

Parameters

buffers One or more data buffers to be written to the file. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.

handler

The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

 void handler(
  const error_code& error, // Result of operation.
  std::size_t bytes_transferred // Number of bytes written.
); 

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using asio::io_service::post().

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

Example: To write a single data buffer use the asio::buffer function as follows:
file.async_write_some(asio::buffer(data, size), handler);
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.

Warning: Interleaving asynchronous writes with other operations that cause the file position/pointer to change is undefined!

Note: Starting multiple asynchronous writes is implementation-defined and not recommended. (A FileService might make additional gurantees, but is not required to.)

◆ async_write_some_at()

template<class FileService >

template<typename ConstBufferSequence , typename WriteHandler >

void_or_deduced asioext::basic_file< FileService >::async_write_some_at	(	uint64_t	offset,
		const ConstBufferSequence &	buffers,
		WriteHandler &&	handler
	)

inline

Start an asynchronous write at the specified offset.

This function is used to asynchronously write data to the file. The function call always returns immediately.

Parameters

offset	The offset at which the data will be written.
buffers	One or more data buffers to be written to the file. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.
handler	The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: void handler( const error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes written. ); Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using asio::io_service::post().

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

Example: To write a single data buffer use the asio::buffer function as follows:
file.async_write_some_at(42, asio::buffer(data, size), handler);
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.

◆ attributes() [1/5]

template<class FileService >

file_attrs asioext::basic_file< FileService >::attributes ( )

inline

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]

template<class FileService >

file_attrs asioext::basic_file< FileService >::attributes ( error_code & ec )

inlinenoexcept

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]

template<class FileService >

void asioext::basic_file< FileService >::attributes	(	file_attrs	attrs,
		file_attr_options	opts = `file_attr_options::replace`
	)

inline

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]

template<class FileService >

void asioext::basic_file< FileService >::attributes	(	file_attrs	attrs,
		error_code &	ec
	)

inlinenoexcept

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]

template<class FileService >

void asioext::basic_file< FileService >::attributes	(	file_attrs	attrs,
		file_attr_options	opts,
		error_code &	ec
	)

inlinenoexcept

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.

◆ cancel() [1/2]

template<class FileService >

void asioext::basic_file< FileService >::cancel ( )

inline

Cancel all asynchronous operations associated with the file.

This function causes all outstanding asynchronous write and read operations to finish immediately, and the handlers for cancelled operations will be passed the asio::error::operation_aborted error.

Exceptions

asio::system_error Thrown on failure.

◆ cancel() [2/2]

template<class FileService >

void asioext::basic_file< FileService >::cancel ( error_code & ec )

inlinenoexcept

Cancel all asynchronous operations associated with the file.

This function causes all outstanding asynchronous write and read operations to finish immediately, and the handlers for cancelled operations will be passed the asio::error::operation_aborted error.

Parameters

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

◆ close() [1/2]

template<class FileService >

void asioext::basic_file< FileService >::close ( )

inline

Close the handle.

This function is used to close the handle.

Exceptions

asio::system_error Thrown on failure.

◆ close() [2/2]

template<class FileService >

void asioext::basic_file< FileService >::close ( error_code & ec )

inlinenoexcept

Close the handle.

This function is used to close the handle.

Parameters

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

◆ is_open()

template<class FileService >

bool asioext::basic_file< FileService >::is_open ( ) const

inlinenoexcept

Determine whether the handle is open.

◆ lowest_layer() [1/2]

template<class FileService >

lowest_layer_type& asioext::basic_file< FileService >::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 basic_file 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]

template<class FileService >

const lowest_layer_type& asioext::basic_file< FileService >::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 basic_file 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()

template<class FileService >

native_handle_type asioext::basic_file< FileService >::native_handle ( )

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.

◆ open() [1/6]

template<class FileService >

void asioext::basic_file< FileService >::open	(	const char *	filename,
		open_flags	flags,
		file_perms	perms = `file_perms::create_default`,
		file_attrs	attrs = `file_attrs::none`
	)

inline

Open a file.

This function closes any currently held handle and attempts to open a handle to the specified file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

filename	The path of the file to open. See Filenames for details.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.

Exceptions

asio::system_error Thrown on failure.

See also: open_flags

◆ open() [2/6]

template<class FileService >

void asioext::basic_file< FileService >::open	(	const char *	filename,
		open_flags	flags,
		file_perms	perms,
		file_attrs	attrs,
		error_code &	ec
	)

inlinenoexcept

Open a file.

This function closes any currently held handle and attempts to open a handle to the specified file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

filename	The path of the file to open. See Filenames for details.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

See also: open_flags

◆ open() [3/6]

template<class FileService >

void asioext::basic_file< FileService >::open	(	const wchar_t *	filename,
		open_flags	flags,
		file_perms	perms = `file_perms::create_default`,
		file_attrs	attrs = `file_attrs::none`
	)

inline

Open a file.

This function closes any currently held handle and attempts to open a handle to the specified file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

filename	The path of the file to open. See Filenames for details.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.

Exceptions

asio::system_error Thrown on failure.

See also: open_flags

Note: Only available on Windows.

◆ open() [4/6]

template<class FileService >

void asioext::basic_file< FileService >::open	(	const wchar_t *	filename,
		open_flags	flags,
		file_perms	perms,
		file_attrs	attrs,
		error_code &	ec
	)

inlinenoexcept

Open a file.

This function closes any currently held handle and attempts to open a handle to the specified file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

filename	The path of the file to open. See Filenames for details.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

See also: open_flags

Note: Only available on Windows.

◆ open() [5/6]

template<class FileService >

void asioext::basic_file< FileService >::open	(	const boost::filesystem::path &	filename,
		open_flags	flags,
		file_perms	perms = `file_perms::create_default`,
		file_attrs	attrs = `file_attrs::none`
	)

inline

Open a file.

This function closes any currently held handle and attempts to open a handle to the specified file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

filename	The path of the file to open. See Filenames for details.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.

Exceptions

asio::system_error Thrown on failure.

See also: open_flags

Note: Only available if using Boost.Filesystem (i.e. if ASIOEXT_HAS_BOOST_FILESYSTEM is defined)

◆ open() [6/6]

template<class FileService >

void asioext::basic_file< FileService >::open	(	const boost::filesystem::path &	filename,
		open_flags	flags,
		file_perms	perms,
		file_attrs	attrs,
		error_code &	ec
	)

inlinenoexcept

Open a file.

This function closes any currently held handle and attempts to open a handle to the specified file.

For details, see open(const char*,open_flags,file_perms,file_attrs)

Parameters

filename	The path of the file to open. See Filenames for details.
flags	Flags used to open the file. For a detailed reference, see asioext::open_flags.
perms	Permissions for newly created files. Unused if an existing file is opened. Defaults to file_perms::create_default.
attrs	Attributes for newly created files. Unused if an existing file is opened. Defaults to file_attrs::none.
ec	Set to indicate what error occurred. If no error occurred, the object is reset.

See also: open_flags

Note: Only available if using Boost.Filesystem (i.e. if ASIOEXT_HAS_BOOST_FILESYSTEM is defined)

◆ permissions() [1/5]

template<class FileService >

file_perms asioext::basic_file< FileService >::permissions ( )

inline

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]

template<class FileService >

file_perms asioext::basic_file< FileService >::permissions ( error_code & ec )

inlinenoexcept

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]

template<class FileService >

void asioext::basic_file< FileService >::permissions	(	file_perms	perms,
		file_perm_options	opts = `file_perm_options::replace`
	)

inline

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]

template<class FileService >

void asioext::basic_file< FileService >::permissions	(	file_perms	perms,
		error_code &	ec
	)

inlinenoexcept

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]

template<class FileService >

void asioext::basic_file< FileService >::permissions	(	file_perms	perms,
		file_perm_options	opts,
		error_code &	ec
	)

inlinenoexcept

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]

template<class FileService >

uint64_t asioext::basic_file< FileService >::position ( )

inline

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]

template<class FileService >

uint64_t asioext::basic_file< FileService >::position ( error_code & ec )

inlinenoexcept

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<class FileService >

template<typename MutableBufferSequence >

std::size_t asioext::basic_file< FileService >::read_some ( const MutableBufferSequence & buffers )

inline

Read some data from the file.

This function is used to read data from the file, starting at the basic_file'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<class FileService >

template<typename MutableBufferSequence >

std::size_t asioext::basic_file< FileService >::read_some	(	const MutableBufferSequence &	buffers,
		error_code &	ec
	)

inlinenoexcept

Read some data from the file.

This function is used to read data from the file, starting at the basic_file'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<class FileService >

template<typename MutableBufferSequence >

std::size_t asioext::basic_file< FileService >::read_some_at	(	uint64_t	offset,
		const MutableBufferSequence &	buffers
	)

inline

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<class FileService >

template<typename MutableBufferSequence >

std::size_t asioext::basic_file< FileService >::read_some_at	(	uint64_t	offset,
		const MutableBufferSequence &	buffers,
		error_code &	ec
	)

inlinenoexcept

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]

template<class FileService >

uint64_t asioext::basic_file< FileService >::seek	(	seek_origin	origin,
		int64_t	offset
	)

inline

Change the read/write position.

This function repositions the current read/write position of this basic_file 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]

template<class FileService >

uint64_t asioext::basic_file< FileService >::seek	(	seek_origin	origin,
		int64_t	offset,
		error_code &	ec
	)

inlinenoexcept

Change the read/write position.

This function repositions the current read/write position of this basic_file 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]

template<class FileService >

uint64_t asioext::basic_file< FileService >::size ( )

inline

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]

template<class FileService >

uint64_t asioext::basic_file< FileService >::size ( error_code & ec )

inlinenoexcept

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]

template<class FileService >

void asioext::basic_file< FileService >::size ( uint64_t new_size )

inline

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]

template<class FileService >

void asioext::basic_file< FileService >::size	(	uint64_t	new_size,
		error_code &	ec
	)

inlinenoexcept

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]

template<class FileService >

file_times asioext::basic_file< FileService >::times ( )

inline

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]

template<class FileService >

file_times asioext::basic_file< FileService >::times ( error_code & ec )

inlinenoexcept

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]

template<class FileService >

void asioext::basic_file< FileService >::times ( const file_times & new_times )

inline

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]

template<class FileService >

void asioext::basic_file< FileService >::times	(	const file_times &	new_times,
		error_code &	ec
	)

inlinenoexcept

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<class FileService >

template<typename ConstBufferSequence >

std::size_t asioext::basic_file< FileService >::write_some ( const ConstBufferSequence & buffers )

inline

Write some data to the file.

This function is used to write data to the file, starting at the basic_file'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 write all of the data. 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<class FileService >

template<typename ConstBufferSequence >

std::size_t asioext::basic_file< FileService >::write_some	(	const ConstBufferSequence &	buffers,
		error_code &	ec
	)

inlinenoexcept

Write some data to the file.

This function is used to write data to the file, starting at the basic_file'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 write all of the data. 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<class FileService >

template<typename ConstBufferSequence >

std::size_t asioext::basic_file< FileService >::write_some_at	(	uint64_t	offset,
		const ConstBufferSequence &	buffers
	)

inline

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<class FileService >

template<typename ConstBufferSequence >

std::size_t asioext::basic_file< FileService >::write_some_at	(	uint64_t	offset,
		const ConstBufferSequence &	buffers,
		error_code &	ec
	)

inlinenoexcept

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

template<class FileService> class asioext::basic_file< FileService >

Member Typedef Documentation

◆ lowest_layer_type

◆ native_handle_type

Constructor & Destructor Documentation

◆ basic_file() [1/9]

◆ basic_file() [2/9]

◆ basic_file() [3/9]

◆ basic_file() [4/9]

◆ basic_file() [5/9]

◆ basic_file() [6/9]

◆ basic_file() [7/9]

◆ basic_file() [8/9]

◆ basic_file() [9/9]

Member Function Documentation

◆ async_read_some()

◆ async_read_some_at()

◆ async_write_some()

◆ async_write_some_at()

◆ attributes() [1/5]

◆ attributes() [2/5]

◆ attributes() [3/5]

◆ attributes() [4/5]

◆ attributes() [5/5]

◆ cancel() [1/2]

◆ cancel() [2/2]

◆ close() [1/2]

◆ close() [2/2]

◆ is_open()

◆ lowest_layer() [1/2]

◆ lowest_layer() [2/2]

◆ native_handle()

◆ open() [1/6]

◆ open() [2/6]

◆ open() [3/6]

◆ open() [4/6]

◆ open() [5/6]

◆ open() [6/6]

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

template<class FileService>
class asioext::basic_file< FileService >