A representation of a file in the filesystem. More...

#include <File.h++>

Inheritance diagram for File:

Collaboration diagram for File:

Public Member Functions
	File (const String &path)
	Construct a new File with the given path. More...

virtual	~File ()
	Destructor. More...

void	open (IOMode mode=IOReadWrite, FileOpenMode openMode=FileOpenElseCreate, const Permissions &perm=Permissions::USER_READ_WRITE)
	Open the file. More...

bool	exists () const
	Test if the file exists. More...

bool	isDirectory () const
	Test if the file is a directory. More...

bool	isFile () const
	Test if the file is a plain file. More...

bool	isPipe () const
	Test if the file is a pipe or socket. More...

bool	isSymLink () const
	Test if the file is a symbolic link. More...

bool	touch ()
	Touch the file. More...

bool	remove ()
	Remove the file. More...

bool	setPermissions (const Permissions &perm)
	Set the file permissions. More...

bool	getPermissions (Permissions &perm)
	Get the file permissions. More...

bool	lockRange (uint64_t start, uint64_t length, LockType type, bool wait=true)
	Lock a range of bytes in the file. More...

bool	unlockRange (uint64_t start, uint64_t length)
	Unlock a range of bytes in the file. More...

void	truncate (uint64_t size=0)
	Truncate the file to a given size. More...

String	getPath () const
	Get the pathname for the file. More...

int64_t	getSize ()
	Get the size of the file. More...

virtual size_t	read (ByteBuffer &buffer)
	Read data from the stream into a ByteBuffer. More...

virtual size_t	read (CharBuffer &buffer)
	Read data from the stream into a CharBuffer. More...

template<typename T >
size_t	read (Buffer< T > &buffer, size_t &partial)
	Read data from the stream into a Buffer of arbitrary type. More...

virtual size_t	read (byte_t *buffer, size_t buflen)
	Read data from the stream into a raw buffer. More...

size_t	read (byte_t *buffer, size_t buflen, int64_t offset, AsyncIOTask &task)
	Read data asynchronously from the stream into a raw buffer. More...

size_t	read (ByteBuffer &buffer, int64_t offset, AsyncIOTask &task)
	Read data asynchronously from the stream into a Buffer. More...

virtual size_t	read (MemoryBlock *vec, uint_t count)
	Read data from the stream into a series of I/O buffers. More...

size_t	write (const byte_t *buffer, size_t buflen, int64_t offset, AsyncIOTask &task)
	Write data asynchronously to the stream from a raw buffer. More...

size_t	write (ByteBuffer &buffer, int64_t offset, AsyncIOTask &task)
	Write data asynchronously to the stream from a Buffer. More...

virtual size_t	write (ByteBuffer &buffer)
	Write data to the stream from a ByteBuffer. More...

virtual size_t	write (CharBuffer &buffer)
	Write data to the stream from a CharBuffer. More...

template<typename T >
size_t	write (Buffer< T > &buffer, size_t &partial)
	Write data to the stream from a Buffer of arbitrary type. More...

virtual size_t	write (const byte_t *buffer, size_t buflen)
	Write data to the stream from a raw buffer, until either the entire buffer is written or an error or timeout occurs. More...

virtual size_t	write (const MemoryBlock *vec, uint_t count)
	Write data to the stream from a series of I/O buffers. More...

virtual size_t	readFully (ByteBuffer &buffer, size_t count=0)
	Read data from the stream into a ByteBuffer, until either the buffer is full or an error or timeout occurs. More...

virtual size_t	readFully (CharBuffer &buffer, size_t count=0)
	Read data from the stream into a CharBuffer, until either the buffer is full or an error or timeout occurs. More...

template<typename T >
size_t	readFully (Buffer< T > &buffer, size_t &partial)
	Read data from the stream into a Buffer of arbitrary type, until either the buffer is full or an error or timeout occurs. More...

virtual size_t	readFully (byte_t *buffer, size_t buflen)
	Read data from the stream into a raw buffer, until either the buffer is full or an error or timeout occurs. More...

virtual size_t	writeFully (ByteBuffer &buffer)
	Write data to the stream from a ByteBuffer, until either the entire buffer is written or an error or timeout occurs. More...

virtual size_t	writeFully (CharBuffer &buffer)
	Write data to the stream from a CharBuffer, until either the entire buffer is written or an error or timeout occurs. More...

template<typename T >
size_t	writeFully (Buffer< T > &buffer, size_t &partial)
	Write data to the stream from a Buffer of arbitrary type, until either the entire buffer is written or an error or timeout occurs. More...

virtual size_t	writeFully (const byte_t *buffer, size_t buflen)
	Write data to the stream from a raw buffer. More...

virtual int64_t	seek (int64_t offset, SeekMode mode=SeekAbsolute)
	Reposition the seek pointer in the stream. More...

virtual int64_t	tell ()
	Get the current (absolute) offset of the seek pointer. More...

bool	isOpen () const
	Test if the stream is open. More...

bool	isSeekable () const
	Test if the stream supports seeking. More...

bool	isReadable () const
	Test if the stream can be read from. More...

bool	isWritable () const
	Test if the stream can be written to. More...

bool	isFullDuplex () const
	Test if the stream is full-duplex (i.e., supports both reading and writing). More...

bool	isHalfDuplex () const
	Test if the stream is half-duplex (i.e., supports either reading or writing, but not both). More...

virtual void	close (IOMode mode=IOReadWrite)
	Close the stream for reading, writing, or both. More...

virtual void	setTimeout (timespan_ms_t timeout)
	Set the stream I/O timeout, in milliseconds. More...

timespan_ms_t	getTimeout () const
	Get the stream I/O timeout, in milliseconds. More...

Static Public Member Functions
static bool	makeDirectory (const String &path, bool createAll=false, const Permissions &perm=Permissions::defaultDirPerms)
	Create a directory. More...

static bool	remove (const String &path)
	Remove a file. More...

static bool	removeDirectory (const String &path)
	Remove a directory. More...

static bool	removeDirectoryTree (const String &path)
	Recursively remove all files and directories rooted at a given directory. More...

static bool	exists (const String &path)
	Test a file for existence. More...

static bool	isDirectory (const String &path)
	Test if a file is a directory. More...

static bool	isFile (const String &path)
	Test if a file is a plain file. More...

static bool	isPipe (const String &path)
	Test if a file is a pipe or socket. More...

static bool	isSymLink (const String &path)
	Test if a file is a symbolic link. More...

static bool	readSymLink (String &path)
	Read a symbolic link. More...

static bool	resolveSymLink (String &path)
	Resolve a symbolic link. More...

static bool	createLink (const String &oldPath, const String &newPath, bool hardLink=false)
	Create a hard or soft link to an existing file. More...

static bool	setPermissions (const String &path, const Permissions &perm)
	Set the permissions on a file. More...

static bool	getPermissions (const String &path, Permissions &perm)
	Get the permissions for a file. More...

static bool	getAttributes (const String &path, FileAttributes &attrs)
	Get file attributes. More...

static int64_t	getSize (const String &path)
	Get the size of a file. More...

static bool	rename (const String &oldName, const String &newName)
	Rename a file. More...

static bool	copy (const String &oldFile, const String &newFile)
	Copy a file to another file. More...

static bool	move (const String &oldFile, const String &newFile)
	Move a file or directory to another location within the same volume or filesystem. More...

static bool	touch (const String &path)
	Touch a file. More...

static String	readToString (const String &path)
	Reads a file into a string. More...

static void	getFileSystemRoots (StringVec &roots, bool localOnly=true)
	Get the filesystem roots. More...

static void	setCreationMask (const Permissions &perm)
	Set the file creation mask for the current process. More...

static uint64_t	getDiskFreeSpace (const String &path)
	Get the amount of free space, in bytes, on the disk or filesystem associated with the given path. More...

static size_t	getDiskBlockSize (const String &path)
	Get the disk block size, in bytes, on the disk or filesystem associated with the given path. More...

static int64_t	roundSizeToBlockSize (const int64_t &fileSize, size_t blockSize)
	Round a file size to the next higher multiple of the given block size. More...

static String	removeTrailingSeparators (const String &path)
	Remove trailing file separators from a file path. More...

static bool	isValidSeparator (char c)
	Determine if a given character is a valid file separator for the host system. More...

static bool	isValidSeparator (char16_t c)
	Determine if a given character is a valid file separator for the host system. More...

Static Public Attributes
static const char	separator = FS
	The host system's file separator character. More...

static const char	validSeparators []
	A string containing all valid file separator characters for the host system. More...

static const char	separatorString [] = { File::separator, NUL }
	The host system's file separator character, as a string. More...

static const char *	eol = EOL
	The host system's end-of-line character sequence. More...

static const uint_t	MAX_IOBLOCK_COUNT = 16
	The maximum number of I/O buffers that can be passed to the vector I/O methods. More...

Protected Member Functions
void	_init (FileHandle handle, bool seekable, bool readable, bool writable)
	Initialize the stream for use with an open file. More...

Protected Attributes
String	_name

Detailed Description

A representation of a file in the filesystem.

The class also provides some static filesystem-related utility functions.

Author: Mark Lindner

Constructor & Destructor Documentation

◆ File()

File ( const String & path )

Construct a new File with the given path.

Parameters

path The path.

◆ ~File()

~File ( )

virtual

Destructor.

Member Function Documentation

◆ _init()

void _init	(	FileHandle	handle,
		bool	seekable,
		bool	readable,
		bool	writable
	)

protectedinherited

Initialize the stream for use with an open file.

Parameters

handle	The handle to an open file.
seekable	A flag indicating whether the stream is seekable.
readable	A flag indicating whether the stream is readable.
writable	A flag indicating whether the stream is writable.

◆ close()

void close ( IOMode mode = IOReadWrite )

virtualinherited

Close the stream for reading, writing, or both.

Parameters

mode	The close mode.

Reimplemented in StreamSocket, and StreamPipe.

◆ copy()

bool copy	(	const String &	oldFile,
		const String &	newFile
	)

static

Copy a file to another file.

Parameters

oldFile	The source file.
newFile	The target file.

Returns: true on success, false otherwise.

◆ createLink()

bool createLink	(	const String &	oldPath,
		const String &	newPath,
		bool	hardLink = `false`
	)

static

Create a hard or soft link to an existing file.

Parameters

oldPath	The path to the existing file.
newPath	The path of the link.
hardLink	A flag indicating whether the link should be a hard link or soft (symbolic) link. Windows only supports hard links, so attempts to create a symbolic link on that platform will fail.

Returns: true on success, false otherwise.

◆ exists() [1/2]

bool exists ( ) const

Test if the file exists.

◆ exists() [2/2]

bool exists ( const String & path )

static

Test a file for existence.

Parameters

path	The path of the file.

Returns: true if the file exists, false otherwise.

◆ getAttributes()

bool getAttributes	(	const String &	path,
		FileAttributes &	attrs
	)

static

Get file attributes.

Parameters

path	The file.
attrs	The FileAttributes object into which the file's attributes should be placed.

Returns: true on success, false otherwise.

◆ getDiskBlockSize()

size_t getDiskBlockSize ( const String & path )

static

Get the disk block size, in bytes, on the disk or filesystem associated with the given path.

Parameters

path	The path. On POSIX systems, the path can refer to any file; the value returned will be the amount of free space on the disk partition containing that file. On Windows systems, the path should be one of the filesystem roots as returned by getFileSystemRoots().

Returns: The size of a disk block, in bytes.

◆ getDiskFreeSpace()

uint64_t getDiskFreeSpace ( const String & path )

static

Get the amount of free space, in bytes, on the disk or filesystem associated with the given path.

Parameters

path	The path. On POSIX systems, the path can refer to any file; the value returned will be the amount of free space on the disk partition containing that file. On Windows systems, the path should be one of the filesystem roots as returned by getFileSystemRoots().

Returns: The amount of free disk space, in bytes.

◆ getFileSystemRoots()

void getFileSystemRoots	(	StringVec &	roots,
		bool	localOnly = `true`
	)

static

Get the filesystem roots.

On POSIX systems there is only one root, namely "/". On Windows, there are multiple roots, corresponding to the mapped drive letters such as "C:", "D:", etc.

Parameters

roots	The vector in which to place the roots.
localOnly	A flag indicating that only roots corresponding to local (non-read-only, non-networked) disks should be returned. This option is only significant on Windows.

◆ getPath()

String getPath ( ) const

inline

Get the pathname for the file.

◆ getPermissions() [1/2]

bool getPermissions ( Permissions & perm )

Get the file permissions.

(NOTE: this call is very slow on Windows.)

Parameters

perm	The Permissions object into which the file's permissions should be placed.

Returns: true on success, false otherwise.

◆ getPermissions() [2/2]

bool getPermissions	(	const String &	path,
		Permissions &	perm
	)

static

Get the permissions for a file.

Parameters

path	The file.
perm	The Permissions object into which the file's permissions should be placed.

Returns: true on success, false otherwise.

◆ getSize() [1/2]

int64_t getSize ( )

Get the size of the file.

Returns: The size of the file.

Exceptions

IOException If an error occurs.

◆ getSize() [2/2]

int64_t getSize ( const String & path )

static

Get the size of a file.

Parameters

path The file.

Returns: The size of the file, in bytes, or -1 if the file was not found.

◆ getTimeout()

timespan_ms_t getTimeout ( ) const

inlineinherited

Get the stream I/O timeout, in milliseconds.

◆ isDirectory() [1/2]

bool isDirectory ( ) const

Test if the file is a directory.

◆ isDirectory() [2/2]

bool isDirectory ( const String & path )

static

Test if a file is a directory.

Parameters

path	The path of the file.

Returns: true if the file exists and is a directory, false otherwise.

◆ isFile() [1/2]

bool isFile ( ) const

Test if the file is a plain file.

◆ isFile() [2/2]

bool isFile ( const String & path )

static

Test if a file is a plain file.

Parameters

path	The path of the file.

Returns: true if the file exists and is a plain file, false otherwise.

◆ isFullDuplex()

bool isFullDuplex ( ) const

inlineinherited

Test if the stream is full-duplex (i.e., supports both reading and writing).

◆ isHalfDuplex()

bool isHalfDuplex ( ) const

inlineinherited

Test if the stream is half-duplex (i.e., supports either reading or writing, but not both).

◆ isOpen()

bool isOpen ( ) const

inlineinherited

Test if the stream is open.

◆ isPipe() [1/2]

bool isPipe ( ) const

Test if the file is a pipe or socket.

◆ isPipe() [2/2]

bool isPipe ( const String & path )

static

Test if a file is a pipe or socket.

Parameters

path	The path of the file.

Returns: true if the file exists and is a pipe or socket, false otherwise.

◆ isReadable()

bool isReadable ( ) const

inlineinherited

Test if the stream can be read from.

◆ isSeekable()

bool isSeekable ( ) const

inlineinherited

Test if the stream supports seeking.

◆ isSymLink() [1/2]

bool isSymLink ( ) const

Test if the file is a symbolic link.

(Some platforms do not support symbolic links.)

Returns: true if the file exists and is a symbolic link, false otherwise.

◆ isSymLink() [2/2]

bool isSymLink ( const String & path )

static

Test if a file is a symbolic link.

(Some platforms do not support symbolic links.)

Parameters

path	The path of the file.

Returns: true if the file exists and is a symbolic link, false otherwise.

◆ isValidSeparator() [1/2]

bool isValidSeparator ( char c )

static

Determine if a given character is a valid file separator for the host system.

◆ isValidSeparator() [2/2]

bool isValidSeparator ( char16_t c )

static

Determine if a given character is a valid file separator for the host system.

◆ isWritable()

bool isWritable ( ) const

inlineinherited

Test if the stream can be written to.

◆ lockRange()

bool lockRange	(	uint64_t	start,
		uint64_t	length,
		LockType	type,
		bool	wait = `true`
	)

Lock a range of bytes in the file.

The type of lock may be mandatory or advisory, depending on what the host system supports.

Parameters

start	The start offset of the range to lock.
length	The length of the range to lock.
type	The type of lock.
wait	A flag indicating whether the method should block until the lock is acquired, or return immediately if it can't be.

Returns: true if the range was successfully locked, false otherwise.

◆ makeDirectory()

bool makeDirectory	(	const String &	path,
		bool	createAll = `false`,
		const Permissions &	perm = `Permissions::defaultDirPerms`
	)

static

Create a directory.

Parameters

path	The path to the new directory.
createAll	A flag indicating whether any nonexsitent intermediate directories in path should also be created.
perm	The permissions to assign to the new directory.

Returns: true if the directory was successfully created (or already existed), false otherwise.

◆ move()

bool move	(	const String &	oldFile,
		const String &	newFile
	)

static

Move a file or directory to another location within the same volume or filesystem.

Parameters

oldFile	The source file.
newFile	The target location.

Returns: true on success, false otherwise.

◆ open()

void open	(	IOMode	mode = `IOReadWrite`,
		FileOpenMode	openMode = `FileOpenElseCreate`,
		const Permissions &	perm = `Permissions::USER_READ_WRITE`
	)

Open the file.

Parameters

mode	The I/O mode.
openMode	The file open mode.
perm	The permissions for the file, if the file is being created.

Exceptions

IOException If an I/O error occurs.

◆ read() [1/7]

size_t read ( ByteBuffer & buffer )

virtualinherited

Read data from the stream into a ByteBuffer.

Parameters

buffer The buffer to read into.

Returns: The number of bytes actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

Reimplemented in StreamSocket.

◆ read() [2/7]

size_t read ( CharBuffer & buffer )

virtualinherited

Read data from the stream into a CharBuffer.

Parameters

buffer The buffer to read into.

Returns: The number of characters actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

Reimplemented in StreamSocket.

◆ read() [3/7]

size_t read	(	Buffer< T > &	buffer,
		size_t &	partial
	)

inlineinherited

Read data from the stream into a Buffer of arbitrary type.

If sizeof(T) is greater than 1 byte, then there can be no guarantee that the number of bytes read before a timeout or error occurs will be evenly divisible by sizeof(T). If the final element was partially read, the number of bytes of the element that were read will be stored in partial; this value should be passed unmodified to the next invocation of this method to continue reading from the appropriate offset within the partially-read element.

Parameters

buffer	The buffer to read into.
partial	The number of bytes remaining to read for a partially-read element; on return, the number of bytes read of a partially-read element, or 0 if the last element was read completely. Should be set to 0 prior to the first call to this method for a fresh buffer.

Returns: The number of whole elements actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

◆ read() [4/7]

size_t read	(	byte_t *	buffer,
		size_t	buflen
	)

virtualinherited

Read data from the stream into a raw buffer.

Parameters

buffer	The buffer to read into.
buflen	The number of bytes to read.

Returns: The number of bytes actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

Reimplemented in StreamSocket.

◆ read() [5/7]

size_t read	(	byte_t *	buffer,
		size_t	buflen,
		int64_t	offset,
		AsyncIOTask &	task
	)

inherited

Read data asynchronously from the stream into a raw buffer.

Parameters

buffer	The buffer to read into.
buflen	The number of bytes to read.
offset	The file offset to read from.
task	The async I/O control block for monitoring the operation.

Returns: The number of bytes actually read, if the operation completed immediately, otherwise 0 to indicate that the operation has begun.

Exceptions

IOException If an I/O error occurred.

◆ read() [6/7]

size_t read	(	ByteBuffer &	buffer,
		int64_t	offset,
		AsyncIOTask &	task
	)

inherited

Read data asynchronously from the stream into a Buffer.

Parameters

buffer	The Buffer to read into. This object must not be destroyed before the asynchronous I/O operation is completed or cancelled.
offset	The file offset to read from.
task	The async I/O control block for monitoring the operation.

Returns: The number of bytes actually read, if the operation completed immediately, otherwise 0 to indicate that the operation has begun.

Exceptions

IOException If an I/O error occurred.

◆ read() [7/7]

size_t read	(	MemoryBlock *	vec,
		uint_t	count
	)

virtualinherited

Read data from the stream into a series of I/O buffers.

This operation is known as "vector read" or "scatter read." The buffers are read into in order. On systems that support it, the operation is performed with a single system call.

Parameters

vec	An array of buffers to read into.
count	The number of buffers in the array.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

Reimplemented in StreamSocket.

◆ readFully() [1/4]

size_t readFully	(	ByteBuffer &	buffer,
		size_t	count = `0`
	)

virtualinherited

Read data from the stream into a ByteBuffer, until either the buffer is full or an error or timeout occurs.

Parameters

buffer	The buffer to read into.
count	The number of bytes to read. If 0 or greater than the number of bytes between the position and the limit, reads up to the limit.

Returns: The number of bytes actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

◆ readFully() [2/4]

size_t readFully	(	CharBuffer &	buffer,
		size_t	count = `0`
	)

virtualinherited

Read data from the stream into a CharBuffer, until either the buffer is full or an error or timeout occurs.

Parameters

buffer	The buffer to read into.
count	The number of characters to read. If 0 or greater than the number of bytes between the position and the limit, reads up to the limit.

Returns: The number of bytes actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

◆ readFully() [3/4]

size_t readFully	(	Buffer< T > &	buffer,
		size_t &	partial
	)

inlineinherited

Read data from the stream into a Buffer of arbitrary type, until either the buffer is full or an error or timeout occurs.

If sizeof(T) is greater than 1 byte, then there can be no guarantee that the number of bytes read before a timeout or error occurs will be evenly divisible by sizeof(T). If the final element was partially read, the number of bytes of the element that were read will be stored in partial; this value should be passed unmodified to the next invocation of this method to continue reading from the appropriate offset within the partially-read element.

Parameters

buffer	The buffer to read into.
partial	The number of bytes remaining to read for a partially-read element; on return, the number of bytes read of a partially-read element, or 0 if the last element was read completely. Should be set to 0 prior to the first call to this method for a fresh buffer.

Returns: The number of whole elements actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

◆ readFully() [4/4]

size_t readFully	(	byte_t *	buffer,
		size_t	buflen
	)

virtualinherited

Read data from the stream into a raw buffer, until either the buffer is full or an error or timeout occurs.

Parameters

buffer	The buffer to read into.
buflen	The number of bytes to read.

Returns: The number of bytes actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

◆ readSymLink()

bool readSymLink ( String & path )

static

Read a symbolic link.

Parameters

path	The path to the symbolic link. On return, the literal path to the file to which the link points (relative to the link itself).

Returns: true on success, or false if the symbolic link could not be read, or if the path does not refer to a symbolic link.

◆ readToString()

String readToString ( const String & path )

static

Reads a file into a string.

The file's contents are assumed to be UTF-8 encoded text.

Parameters

path	The path to the file.

Returns: The contents of tha file, as a String, or String::null if an error occurred while reading the file.

◆ remove() [1/2]

bool remove ( )

Remove the file.

Returns: true if the file was successfully removed, false otherwise.

◆ remove() [2/2]

bool remove ( const String & path )

static

Remove a file.

Parameters

path	The path to the file.

Returns: true if the file was successfully removed, false otherwise.

◆ removeDirectory()

bool removeDirectory ( const String & path )

static

Remove a directory.

Only empty directories may be removed using this function.

Parameters

path	The path to the directory.

Returns: true if the directory was successfully removed, false otherwise.

◆ removeDirectoryTree()

bool removeDirectoryTree ( const String & path )

static

Recursively remove all files and directories rooted at a given directory.

The removal process will not be interrupted if any errors are encountered.

Parameters

path	The path to the root of the directory tree to remove.

Returns: true if the directory tree was successfully removed, false if any errors occurred during the removal.

◆ removeTrailingSeparators()

String removeTrailingSeparators ( const String & path )

static

Remove trailing file separators from a file path.

Parameters

path The path.

Returns: The path with trailing file separators removed.

◆ rename()

bool rename	(	const String &	oldName,
		const String &	newName
	)

static

Rename a file.

Parameters

oldName	The file to rename.
newName	The new name for the file.

Returns: true on success, false otherwise.

◆ resolveSymLink()

bool resolveSymLink ( String & path )

static

Resolve a symbolic link.

Parameters

path	The path to the symbolic link. On return, the canonical path to the file to which the link points.

Returns: true on success, or false if the symbolic link could not be read, or if the path does not refer to a symbolic link.

◆ roundSizeToBlockSize()

int64_t roundSizeToBlockSize	(	const int64_t &	fileSize,
		size_t	blockSize
	)

static

Round a file size to the next higher multiple of the given block size.

This method may be used to determine the actual amount of space that a file occupies on disk.

Parameters

fileSize	The file size.
blockSize	The block size.

Returns: The rounded file size.

◆ seek()

int64_t seek	(	int64_t	offset,
		SeekMode	mode = `SeekAbsolute`
	)

virtualinherited

Reposition the seek pointer in the stream.

Parameters

offset	The new offset.
mode	The seek mode.

Returns: The new position of the seek pointer.

Exceptions

IOException If the stream does not support seeking, or if some other I/O error occurred.

◆ setCreationMask()

void setCreationMask ( const Permissions & perm )

static

Set the file creation mask for the current process.

This function is POSIX-specific; it has no effect on Windows.

Parameters

perm	The permissions that will be turned off on newly created files.

◆ setPermissions() [1/2]

bool setPermissions ( const Permissions & perm )

Set the file permissions.

Parameters

perm	The Permissions to set.

Returns: true on success, false otherwise.

◆ setPermissions() [2/2]

bool setPermissions	(	const String &	path,
		const Permissions &	perm
	)

static

Set the permissions on a file.

Parameters

path	The file.
perm	The Permissions to set.

Returns: true on success, false otherwise.

◆ setTimeout()

void setTimeout ( timespan_ms_t timeout )

virtualinherited

Set the stream I/O timeout, in milliseconds.

A timeout of 0 indicates no timeout, and a timeout of -1 indicates infinite timeout (blocking I/O).

Reimplemented in StreamSocket, and SerialPort.

◆ tell()

int64_t tell ( )

virtualinherited

Get the current (absolute) offset of the seek pointer.

Returns: The current offset, from the beginning of the stream.

Exceptions

IOException If the stream does not support seeking, or if some other I/O error occurred.

◆ touch() [1/2]

bool touch ( )

Touch the file.

The file's last-accessed timestamp is updated if the file exists; otherwise the file is created as an empty file.

Returns: true on success, false otherwise.

◆ touch() [2/2]

bool touch ( const String & path )

static

Touch a file.

The file's last-accessed timestamp is updated if the file exists; otherwise the file is created as an empty file.

Parameters

path	The path to the file.

Returns: true on success, false otherwise.

◆ truncate()

void truncate ( uint64_t size = 0 )

Truncate the file to a given size.

On return, the file seek pointer will be at the end of the file.

Parameters

size	The new size of the file, which must be less than or equal to the file's current size. Truncating a file to extend its size produces different results on POSIX vs. Windows systems, and thus is not supported.

Exceptions

IOException If the operation fails, or if the specified size is greater than the file's current size.

◆ unlockRange()

bool unlockRange	(	uint64_t	start,
		uint64_t	length
	)

Unlock a range of bytes in the file.

The range must match a range that was previously locked with lockRange().

Parameters

start	The start offset of the range to unlock.
length	The length of the range to unlock.

Returns: true if the range was successfully unlocked, false otherwise.

◆ write() [1/7]

size_t write	(	const byte_t *	buffer,
		size_t	buflen,
		int64_t	offset,
		AsyncIOTask &	task
	)

inherited

Write data asynchronously to the stream from a raw buffer.

Parameters

buffer	The buffer to write.
buflen	The number of bytes to write.
offset	The file offset to write to.
task	The async I/O control block for monitoring the operation.

Returns: The number of bytes actually written, if the operation completed immediately, otherwise 0 to indicate that the operation has begun.

Exceptions

IOException If an I/O error occurred.

◆ write() [2/7]

size_t write	(	ByteBuffer &	buffer,
		int64_t	offset,
		AsyncIOTask &	task
	)

inherited

Write data asynchronously to the stream from a Buffer.

Parameters

buffer	The Buffer to write. This object must not be destroyed before the asynchronous I/O operation is completed or cancelled.
offset	The file offset to write to.
task	The async I/O control block for monitoring the operation.

Returns: The number of bytes actually written, if the operation completed immediately, otherwise 0 to indicate that the operation has begun.

Exceptions

IOException If an I/O error occurred.

◆ write() [3/7]

size_t write ( ByteBuffer & buffer )

virtualinherited

Write data to the stream from a ByteBuffer.

Parameters

buffer The buffer to write.

Returns: The number of bytes actually written.

Exceptions

IOException If an I/O error occurred.

Reimplemented in StreamSocket.

◆ write() [4/7]

size_t write ( CharBuffer & buffer )

virtualinherited

Write data to the stream from a CharBuffer.

Parameters

buffer The buffer to write.

Returns: The number of characters actually written.

Exceptions

IOException If an I/O error occurred.

Reimplemented in StreamSocket.

◆ write() [5/7]

size_t write	(	Buffer< T > &	buffer,
		size_t &	partial
	)

inlineinherited

Write data to the stream from a Buffer of arbitrary type.

If sizeof(T) is greater than 1 byte, then there can be no guarantee that the number of bytes written before a timeout or error occurs will be evenly divisible by sizeof(T). If the final element was partially written, the number of bytes of the element that were written will be stored in partial; this value should be passed unmodified to the next invocation of this method to continue writing from the appropriate offset within the partially-written element.

Parameters

buffer	The buffer to write.
partial	The number of bytes remaining to write for a partially-written element; on return, the number of bytes written of a partially-written element, or 0 if the last element was written completely. Should be set to 0 prior to the first call to this method for a fresh buffer.

Returns: The number of whole elements actually written.

Exceptions

IOException If an I/O error occurred.

◆ write() [6/7]

size_t write	(	const byte_t *	buffer,
		size_t	buflen
	)

virtualinherited

Write data to the stream from a raw buffer, until either the entire buffer is written or an error or timeout occurs.

Parameters

buffer	A pointer to the buffer.
buflen	The number of bytes to write.

Returns: The number of bytes actually written.

Exceptions

IOException If an I/O error occurred.

Reimplemented in StreamSocket.

◆ write() [7/7]

size_t write	(	const MemoryBlock *	vec,
		uint_t	count
	)

virtualinherited

Write data to the stream from a series of I/O buffers.

This operation is known as "vector write" or "gather write." The buffers are written in order. On systems that support it, the operation is performed with a single system call.

Parameters

vec	An array of buffers to write.
count	The number of buffers in the array.

Exceptions

IOException If an I/O error occurred.

Reimplemented in StreamSocket.

◆ writeFully() [1/4]

size_t writeFully ( ByteBuffer & buffer )

virtualinherited

Write data to the stream from a ByteBuffer, until either the entire buffer is written or an error or timeout occurs.

Parameters

buffer The buffer to write.

Returns: The number of bytes actually written.

Exceptions

IOException If and I/O error occurred.

◆ writeFully() [2/4]

size_t writeFully ( CharBuffer & buffer )

virtualinherited

Write data to the stream from a CharBuffer, until either the entire buffer is written or an error or timeout occurs.

Parameters

buffer The buffer to write.

Returns: The number of bytes actually written.

Exceptions

IOException If an I/O error occurred.

◆ writeFully() [3/4]

size_t writeFully	(	Buffer< T > &	buffer,
		size_t &	partial
	)

inlineinherited

Write data to the stream from a Buffer of arbitrary type, until either the entire buffer is written or an error or timeout occurs.

If sizeof(T) is greater than 1 byte, then there can be no guarantee that the number of bytes written before a timeout or error occurs will be evenly divisible by sizeof(T). If the final element was partially written, the number of bytes of the element that were written will be stored in partial; this value should be passed unmodified to the next invocation of this method to continue writing from the appropriate offset within the partially-written element.

Parameters

buffer	The buffer to write.
partial	The number of bytes remaining to write for a partially-written element; on return, the number of bytes written of a partially-written element, or 0 if the last element was written completely. Should be set to 0 prior to the first call to this method for a fresh buffer.

Returns: The number of whole elements actually written.

Exceptions

IOException If an I/O error occurred.

◆ writeFully() [4/4]

size_t writeFully	(	const byte_t *	buffer,
		size_t	buflen
	)

virtualinherited

Write data to the stream from a raw buffer.

Parameters

buffer	A pointer to the buffer.
buflen	The number of bytes to write.

Returns: The number of bytes actually written.

Exceptions

IOException If an I/O error occurred.

Member Data Documentation

◆ _name

String _name

protected

◆ eol

const char * eol = EOL

static

The host system's end-of-line character sequence.

◆ MAX_IOBLOCK_COUNT

const uint_t MAX_IOBLOCK_COUNT = 16

staticinherited

The maximum number of I/O buffers that can be passed to the vector I/O methods.

◆ separator

const char separator = FS

static

The host system's file separator character.

◆ separatorString

const char separatorString = { File::separator, NUL }

static

The host system's file separator character, as a string.

◆ validSeparators

const char validSeparators

static

Initial value:

= { File::separator,
                                       NUL }

A string containing all valid file separator characters for the host system.

On Windows, this string includes both `/' and '\', while on all other systems it is equivalent to File::separator.

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ File()

◆ ~File()

Member Function Documentation

◆ _init()

◆ close()

◆ copy()

◆ createLink()

◆ exists() [1/2]

◆ exists() [2/2]

◆ getAttributes()

◆ getDiskBlockSize()

◆ getDiskFreeSpace()

◆ getFileSystemRoots()

◆ getPath()

◆ getPermissions() [1/2]

◆ getPermissions() [2/2]

◆ getSize() [1/2]

◆ getSize() [2/2]

◆ getTimeout()

◆ isDirectory() [1/2]

◆ isDirectory() [2/2]

◆ isFile() [1/2]

◆ isFile() [2/2]

◆ isFullDuplex()

◆ isHalfDuplex()

◆ isOpen()

◆ isPipe() [1/2]

◆ isPipe() [2/2]

◆ isReadable()

◆ isSeekable()

◆ isSymLink() [1/2]

◆ isSymLink() [2/2]

◆ isValidSeparator() [1/2]

◆ isValidSeparator() [2/2]

◆ isWritable()

◆ lockRange()

◆ makeDirectory()

◆ move()

◆ open()

◆ read() [1/7]

◆ read() [2/7]

◆ read() [3/7]

◆ read() [4/7]

◆ read() [5/7]

◆ read() [6/7]

◆ read() [7/7]

◆ readFully() [1/4]

◆ readFully() [2/4]

◆ readFully() [3/4]

◆ readFully() [4/4]

◆ readSymLink()

◆ readToString()

◆ remove() [1/2]

◆ remove() [2/2]

◆ removeDirectory()

◆ removeDirectoryTree()

◆ removeTrailingSeparators()

◆ rename()

◆ resolveSymLink()

◆ roundSizeToBlockSize()

◆ seek()

◆ setCreationMask()

◆ setPermissions() [1/2]

◆ setPermissions() [2/2]

◆ setTimeout()

◆ tell()

◆ touch() [1/2]

◆ touch() [2/2]

◆ truncate()

◆ unlockRange()

◆ write() [1/7]

◆ write() [2/7]

◆ write() [3/7]