#include <base/io/File.h>

Inherits Resource, and AsynchronousIOStream.

Public Types
enum	Access { READ, WRITE, READWRITE }

enum	Whence { BEGIN, CURRENT, END }

enum	Options { CREATE = 1, TRUNCATE = 2, EXCLUSIVE = 4, ASYNCHRONOUS = 8, APPEND = 16 }

enum	Sticky { SET_UID = 0x4000, SET_GID = 0x2000, RESTRICT = 0x1000, STICKY_MASK = SET_UID\|SET_GID\|RESTRICT }

enum	Permissions { RUSR = 0x400, WUSR = 0x200, XUSR = 0x100, RWXU = RUSR\|WUSR\|XUSR, RGRP = 0x40, WGRP = 0x20, XGRP = 0x10, RWXG = RGRP\|WGRP\|XGRP, ROTH = 0x4, WOTH = 0x2, XOTH = 0x1, RWXO = ROTH\|WOTH\|XOTH, PERMISSION_MASK = RWXU\|RWXG\|RWXO }

enum	Variable { MIN_FILE_SIZE_BITS, MAX_NUM_OF_LINKS, MAX_LEN_OF_NAME, MAX_LEN_OF_PATH, MAX_SIZE_OF_PIPE_BUFFER, MAX_SIZE_OF_SYMLINK }

enum	Encoding { ENCODING_RAW, ENCODING_ASCII, ENCODING_UTF8, ENCODING_UTF8_ISO }

Public Member Functions
	File () noexcept

	File (const String &path, Access access, unsigned int options)

void	close ()

bool	isClosed () const noexcept

AccessControlList	getACL () const

Trustee	getOwner () const

Trustee	getGroup () const

unsigned int	getMode () const

long long	getSize () const

long long	getPosition () const

void	setPosition (long long position, Whence whence=BEGIN)

void	truncate (long long size)

void	flush ()

void	lock (const FileRegion &region, bool exclusive=true)

bool	tryLock (const FileRegion &region, bool exclusive=true)

void	unlock (const FileRegion &region)

Date	getLastModification ()

Date	getLastAccess ()

Date	getLastChange ()

unsigned long	getVariable (Variable variable)

unsigned int	read (uint8 *buffer, unsigned int size, bool nonblocking=false)

template<class TYPE >
unsigned int	read (TYPE &buffer)

unsigned int	write (const uint8 *buffer, unsigned int size, bool nonblocking=false)

OperatingSystem::Handle	getHandle () const noexcept

void	asyncCancel ()

AsynchronousReadOperation	read (uint8 buffer, unsigned int bytesToRead, unsigned long long offset, AsynchronousReadEventListener listener)

AsynchronousWriteOperation	write (const uint8 buffer, unsigned int bytesToWrite, unsigned long long offset, AsynchronousWriteEventListener listener)

	~File ()

Public Member Functions inherited from Resource
String	getDescription () const

void	setDescription (const String &description)

unsigned int	getResourceId () const

unsigned int	getCreatedById () const

AnyReference	getHandle () const noexcept

template<class TYPE >
TYPE &	getInternalHandle () const

	operator bool () const noexcept

Public Member Functions inherited from AsynchronousStream
virtual	~AsynchronousStream () noexcept(false)

Static Public Member Functions
static void	changeOwner (const String &path, const Trustee &owner, const Trustee &group, bool followLink=true)

static bool	createFile (const String &path, const uint8 *buffer, MemorySize size)

static bool	createFile (const String &path, const String &text)

static Validified< String >	readFile (const String &path, Encoding encoding=ENCODING_UTF8)

Static Public Member Functions inherited from AsynchronousStream
static bool	asyncTest () noexcept

Additional Inherited Members
Protected Attributes inherited from Resource
AnyReference	handle

Detailed Description

File.

A file.

Version: 1.1

Examples: testsuite/ftp.cpp, testsuite/http.cpp, and testsuite/xsltprocessor.cpp.

Member Enumeration Documentation

◆ Access

enum File::Access

File access.

Enumerator
READ	Request read access.
WRITE	Request write access.
READWRITE	Request read and write access.

◆ Options

enum File::Options

File initialization options.

Enumerator
CREATE	Specifies that the file should be created if it doesn't exist.
TRUNCATE	Specifies that the file should be truncated if it already exists.
EXCLUSIVE	Specifies that the file should be opened in exclusive mode.
ASYNCHRONOUS	Specifies that the file should be opened for asynchronous IO (disables the synchronous IO interface).
APPEND	Specifies that data should be appended to the file.

◆ Permissions

enum File::Permissions

Permissions.

Enumerator
RUSR	Read permission for the owner of the file.
WUSR	Write permission for the owner of the file.
XUSR	Execute permission for the owner of the file.
RWXU	Read, write, and execute permissions for the owner of the file.
RGRP	Read permission for the group associated with the file.
WGRP	Write permission for the group associated with the file.
XGRP	Execute permission for the group associated with the file.
RWXG	Read, write, and execute permissions for the group associated with the file.
ROTH	Read permission for other users.
WOTH	Write permission for other users.
XOTH	Execute permission for other users.
RWXO	Read, write, and execute permissions for other users.
PERMISSION_MASK	Any access.

◆ Sticky

enum File::Sticky

Sticky bit.

Enumerator
SET_UID	Set user id on execution.
SET_GID	Set group id on execution.
RESTRICT	Restrict flag.
STICKY_MASK	All sticky bits.

◆ Variable

enum File::Variable

File system variables.

Enumerator
MIN_FILE_SIZE_BITS	Specifies the minimum number of bits required to represent the maximum supported file size.
MAX_NUM_OF_LINKS	Specifies the maximum number of links to a file.
MAX_LEN_OF_NAME	Specifies the maximum length of a file name.
MAX_LEN_OF_PATH	Specifies the maximum length of a path.
MAX_SIZE_OF_PIPE_BUFFER	Specifies the maximum number bytes that is guaranteed to be atomic when writing to a pipe.
MAX_SIZE_OF_SYMLINK	Specifies the maximum number of bytes in a symbolic link.

◆ Whence

enum File::Whence

Type used to specify the relative offset.

Enumerator
BEGIN	Position is relative to begining of file.
CURRENT	Position is relative to current position of file.
END	Position is relative to end of file.

Constructor & Destructor Documentation

◆ File() [1/2]

File::File ( )

noexcept

Initializes an invalid file object (correspons to a closed file).

◆ File() [2/2]

File::File	(	const String &	path,
		Access	access,
		unsigned int	options
	)

Initializes a file. If no options are specified the initialization will fail if the file doesn't exist.

Parameters

path	the path of the file.
access	The desired access to the files.
option	Additional options (i.e. CREATE, TRUNCATE, EXCLUSIVE).

◆ ~File()

File::~File ( )

Destroys the file.

Member Function Documentation

◆ asyncCancel()

void File::asyncCancel ( )

Aborts any pending asynchronous operations (read as well as write).

◆ changeOwner()

static void File::changeOwner	(	const String &	path,
		const Trustee &	owner,
		const Trustee &	group,
		bool	followLink = `true`
	)

static

Sets the owner of the file.

Parameters

path	The path of the file.
owner	The new owner of the file.
group	The primary group of the file.
followLink	Specifies whether or not to follow the link.

◆ close()

void File::close ( )

Closes the file.

Examples: testsuite/http.cpp.

◆ createFile() [1/2]

static bool File::createFile	(	const String &	path,
		const String &	text
	)

static

Creates a file from the given string. Saves the raw bytes.

Returns: Returns true on success.

◆ createFile() [2/2]

static bool File::createFile	(	const String &	path,
		const uint8 *	buffer,
		MemorySize	size
	)

static

Creates a file from the given string. Saves the raw bytes.

Returns: Returns true on succefss.

◆ flush()

void File::flush ( )

Flushes any buffered data.

◆ getACL()

AccessControlList File::getACL ( ) const

Returns the Access Control List (ACL) of the file.

◆ getGroup()

Trustee File::getGroup ( ) const

Returns the group of the file.

◆ getHandle()

OperatingSystem::Handle File::getHandle ( ) const

virtualnoexcept

Returns the OS handle.

Implements AsynchronousIOStream.

◆ getLastAccess()

Date File::getLastAccess ( )

Returns the last access time of the file.

◆ getLastChange()

Date File::getLastChange ( )

Returns the last chnage time of the file.

◆ getLastModification()

Date File::getLastModification ( )

Returns the last modification time of the file.

◆ getMode()

unsigned int File::getMode ( ) const

Returns the permissions of the file.

◆ getOwner()

Trustee File::getOwner ( ) const

Returns the owner of the file.

◆ getPosition()

long long File::getPosition ( ) const

Returns the current position.

◆ getSize()

long long File::getSize ( ) const

Returns the size of the file in bytes.

Examples: testsuite/xsltprocessor.cpp.

◆ getVariable()

unsigned long File::getVariable ( Variable variable )

Returns the value of the specified file system variable.

◆ isClosed()

bool File::isClosed ( ) const

noexcept

Returns true if the file object has been closed (or need has been opened).

◆ lock()

void File::lock	(	const FileRegion &	region,
		bool	exclusive = `true`
	)

Locks the specified region of the file. Blocks until lock has been acquired. Exclusive locks require the file to be opened with write access.

Parameters

region	The file region to be locked.
exclusive	Specifies that the region should be locked exclusively. Default is true.

◆ read() [1/3]

template<class TYPE >

unsigned int File::read ( TYPE & buffer )

inline

Read the specified type.

◆ read() [2/3]

AsynchronousReadOperation File::read	(	uint8 *	buffer,
		unsigned int	bytesToRead,
		unsigned long long	offset,
		AsynchronousReadEventListener *	listener
	)

virtual

Requests and asynchronous read operation. Asynchronous IO is only supported if the file has been opened in asynchronous mode.

Parameters

buffer	The bytes to be read.
bytesToRead	The number of bytes to be read.
offset	The offset from the beginning of the file.
listener	The listener to be notified on completion.

Implements AsynchronousIOStream.

◆ read() [3/3]

unsigned int File::read	(	uint8 *	buffer,
		unsigned int	size,
		bool	nonblocking = `false`
	)

If another process has acquired an exclusive lock on part of the file region to be read, the read request will block until the lock has been released.

Returns: 0 if the end of the file has been reached (or if requested to read 0 bytes).

Examples: testsuite/xsltprocessor.cpp.

◆ readFile()

static Validified<String> File::readFile	(	const String &	path,
		Encoding	encoding = `ENCODING_UTF8`
	)

static

Reads bytes from file to string.

Parameters

path	The file path.
encoding	The encoding. Defaults to UTF-8 Unicode.

◆ setPosition()

void File::setPosition	(	long long	position,
		Whence	whence = `BEGIN`
	)

Sets the position.

Parameters

position	The relative offset from the specified base offset.
whence	Specifies the base offset. The default is the beginning of the file.

◆ truncate()

void File::truncate ( long long size )

Truncates the file to the specified size. The file must have been opened with write access. If the file previously was larger than the specified size, the extra data is discarded. If the file was previously shorter, it is extended with zeros.

◆ tryLock()

bool File::tryLock	(	const FileRegion &	region,
		bool	exclusive = `true`
	)

Tries to lock specified region of the file. Exclusive locks require the file to be opened with write access.

Parameters

region	The file region to be locked.
exclusive	Specifies that the region should be locked exclusively. Default is true.

Returns: True if the lock was acquired.

◆ unlock()

void File::unlock ( const FileRegion & region )

Unlocks the specified region of the file.

Parameters

region The file region to be unlocked.

◆ write() [1/2]

AsynchronousWriteOperation File::write	(	const uint8 *	buffer,
		unsigned int	bytesToWrite,
		unsigned long long	offset,
		AsynchronousWriteEventListener *	listener
	)

virtual

Requests and asynchronous write operation. Asynchronous IO is only supported if the file has been opened in asynchronous mode.

Parameters

buffer	The bytes to be written.
bytesToWrite	The number of bytes to be written.
offset	The offset from the beginning of the file.
listener	The listener to be notified on completion.

Implements AsynchronousIOStream.

◆ write() [2/2]

unsigned int File::write	(	const uint8 *	buffer,
		unsigned int	size,
		bool	nonblocking = `false`
	)

Raises EndOfFile if minimum number of bytes cannot be read without exceeding the end of the file.

Examples: testsuite/http.cpp.

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Access

◆ Options

◆ Permissions

◆ Sticky

◆ Variable

◆ Whence

Constructor & Destructor Documentation

◆ File() [1/2]

◆ File() [2/2]

◆ ~File()

Member Function Documentation

◆ asyncCancel()

◆ changeOwner()

◆ close()

◆ createFile() [1/2]

◆ createFile() [2/2]

◆ flush()

◆ getACL()

◆ getGroup()

◆ getHandle()

◆ getLastAccess()

◆ getLastChange()

◆ getLastModification()

◆ getMode()

◆ getOwner()

◆ getPosition()

◆ getSize()

◆ getVariable()

◆ isClosed()

◆ lock()

◆ read() [1/3]

◆ read() [2/3]

◆ read() [3/3]

◆ readFile()

◆ setPosition()

◆ truncate()

◆ tryLock()

◆ unlock()

◆ write() [1/2]

◆ write() [2/2]