File Class Reference

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

#include <File.h++>

Inheritance diagram for File:

Public Member Functions
	File (const String &path)
	Construct a new File with the given path.
virtual	~File () throw ()
	Destructor.
void	open (IOMode mode=IOReadWrite, FileOpenMode openMode=FileOpenElseCreate, const Permissions &perm=Permissions::USER_READ_WRITE) throw (IOException)
	Open the file.
bool	exists () const throw ()
	Test if the file exists.
bool	isDirectory () const throw ()
	Test if the file is a directory.
bool	isFile () const throw ()
	Test if the file is a plain file.
bool	isPipe () const throw ()
	Test if the file is a pipe or socket.
bool	isSymLink () const throw ()
	Test if the file is a symbolic link.
bool	touch () throw ()
	Touch the file.
bool	remove () throw ()
	Remove the file.
bool	setPermissions (const Permissions &perm) throw ()
	Set the file permissions.
bool	getPermissions (Permissions &perm) throw ()
	Get the file permissions.
bool	lockRange (uint64_t start, uint64_t length, LockType type, bool wait=true) throw ()
	Lock a range of bytes in the file.
bool	unlockRange (uint64_t start, uint64_t length) throw ()
	Unlock a range of bytes in the file.
void	truncate (uint64_t size=0) throw (IOException)
	Truncate the file to a given size.
String	getPath () const
	Get the pathname for the file.
int64_t	getSize () throw (IOException)
	Get the size of the file.
virtual size_t	read (ByteBuffer &buffer) throw (IOException)
	Read data from the stream into a ByteBuffer.
virtual size_t	read (CharBuffer &buffer) throw (IOException)
	Read data from the stream into a CharBuffer.
template<typename T >
size_t	read (Buffer< T > &buffer, size_t &partial) throw (IOException)
	Read data from the stream into a Buffer of arbitrary type.
virtual size_t	read (byte_t *buffer, size_t buflen) throw (IOException)
	Read data from the stream into a raw buffer.
size_t	read (byte_t *buffer, size_t buflen, int64_t offset, AsyncIOTask &task) throw (IOException)
	Read data asynchronously from the stream into a raw buffer.
size_t	read (ByteBuffer &buffer, int64_t offset, AsyncIOTask &task) throw (IOException)
	Read data asynchronously from the stream into a Buffer.
virtual size_t	read (MemoryBlock *vec, uint_t count) throw (IOException)
	Read data from the stream into a series of I/O buffers.
size_t	write (const byte_t *buffer, size_t buflen, int64_t offset, AsyncIOTask &task) throw (IOException)
	Write data asynchronously to the stream from a raw buffer.
size_t	write (ByteBuffer &buffer, int64_t offset, AsyncIOTask &task) throw (IOException)
	Write data asynchronously to the stream from a Buffer.
virtual size_t	write (ByteBuffer &buffer) throw (IOException)
	Write data to the stream from a ByteBuffer.
virtual size_t	write (CharBuffer &buffer) throw (IOException)
	Write data to the stream from a CharBuffer.
template<typename T >
size_t	write (Buffer< T > &buffer, size_t &partial) throw (IOException)
	Write data to the stream from a Buffer of arbitrary type.
virtual size_t	write (const byte_t *buffer, size_t buflen) throw (IOException)
	Write data to the stream from a raw buffer, until either the entire buffer is written or an error or timeout occurs.
virtual size_t	write (const MemoryBlock *vec, uint_t count) throw (IOException)
	Write data to the stream from a series of I/O buffers.
virtual size_t	readFully (ByteBuffer &buffer, size_t count=0) throw (IOException)
	Read data from the stream into a ByteBuffer, until either the buffer is full or an error or timeout occurs.
virtual size_t	readFully (CharBuffer &buffer, size_t count=0) throw (IOException)
	Read data from the stream into a CharBuffer, until either the buffer is full or an error or timeout occurs.
template<typename T >
size_t	readFully (Buffer< T > &buffer, size_t &partial) throw (IOException)
	Read data from the stream into a Buffer of arbitrary type, until either the buffer is full or an error or timeout occurs.
virtual size_t	readFully (byte_t *buffer, size_t buflen) throw (IOException)
	Read data from the stream into a raw buffer, until either the buffer is full or an error or timeout occurs.
virtual size_t	writeFully (ByteBuffer &buffer) throw (IOException)
	Write data to the stream from a ByteBuffer, until either the entire buffer is written or an error or timeout occurs.
virtual size_t	writeFully (CharBuffer &buffer) throw (IOException)
	Write data to the stream from a CharBuffer, until either the entire buffer is written or an error or timeout occurs.
template<typename T >
size_t	writeFully (Buffer< T > &buffer, size_t &partial) throw (IOException)
	Write data to the stream from a Buffer of arbitrary type, until either the entire buffer is written or an error or timeout occurs.
virtual size_t	writeFully (const byte_t *buffer, size_t buflen) throw (IOException)
	Write data to the stream from a raw buffer.
virtual int64_t	seek (int64_t offset, SeekMode mode=SeekAbsolute) throw (IOException)
	Reposition the seek pointer in the stream.
virtual int64_t	tell () throw (IOException)
	Get the current (absolute) offset of the seek pointer.
bool	isOpen () const throw ()
	Test if the stream is open.
bool	isSeekable () const throw ()
	Test if the stream supports seeking.
bool	isReadable () const throw ()
	Test if the stream can be read from.
bool	isWritable () const throw ()
	Test if the stream can be written to.
bool	isFullDuplex () const throw ()
	Test if the stream is full-duplex (i.e., supports both reading and writing).
bool	isHalfDuplex () const throw ()
	Test if the stream is half-duplex (i.e., supports either reading or writing, but not both).
virtual void	close (IOMode mode=IOReadWrite) throw ()
	Close the stream for reading, writing, or both.
virtual void	setTimeout (timespan_ms_t timeout) throw (IOException)
	Set the stream I/O timeout, in milliseconds.
timespan_ms_t	getTimeout () const throw ()
	Get the stream I/O timeout, in milliseconds.
Static Public Member Functions
static bool	makeDirectory (const String &path, bool createAll=false, const Permissions &perm=Permissions::defaultDirPerms) throw ()
	Create a directory.
static bool	remove (const String &path) throw ()
	Remove a file.
static bool	removeDirectory (const String &path) throw ()
	Remove a directory.
static bool	removeDirectoryTree (const String &path)
	Recursively remove all files and directories rooted at a given directory.
static bool	exists (const String &path) throw ()
	Test a file for existence.
static bool	isDirectory (const String &path) throw ()
	Test if a file is a directory.
static bool	isFile (const String &path) throw ()
	Test if a file is a plain file.
static bool	isPipe (const String &path) throw ()
	Test if a file is a pipe or socket.
static bool	isSymLink (const String &path) throw ()
	Test if a file is a symbolic link.
static bool	readSymLink (String &path) throw ()
	Read a symbolic link.
static bool	resolveSymLink (String &path) throw ()
	Resolve a symbolic link.
static bool	createLink (const String &oldPath, const String &newPath, bool hardLink=false) throw ()
	Create a hard or soft link to an existing file.
static bool	setPermissions (const String &path, const Permissions &perm) throw ()
	Set the permissions on a file.
static bool	getPermissions (const String &path, Permissions &perm) throw ()
	Get the permissions for a file.
static bool	getAttributes (const String &path, FileAttributes &attrs) throw ()
	Get file attributes.
static int64_t	getSize (const String &path) throw ()
	Get the size of a file.
static bool	rename (const String &oldName, const String &newName) throw ()
	Rename a file.
static bool	copy (const String &oldFile, const String &newFile) throw ()
	Copy a file to another file.
static bool	move (const String &oldFile, const String &newFile) throw ()
	Move a file or directory to another location within the same volume or filesystem.
static bool	touch (const String &path) throw ()
	Touch a file.
static void	getFileSystemRoots (StringVec &roots, bool localOnly=true) throw ()
	Get the filesystem roots.
static void	setCreationMask (const Permissions &perm) throw ()
	Set the file creation mask for the current process.
static uint64_t	getDiskFreeSpace (const String &path) throw ()
	Get the amount of free space, in bytes, on the disk or filesystem associated with the given path.
static size_t	getDiskBlockSize (const String &path) throw ()
	Get the disk block size, in bytes, on the disk or filesystem associated with the given path.
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.
static String	removeTrailingSeparators (const String &path) throw ()
	Remove trailing file separators from a file path.
static bool	isValidSeparator (char c) throw ()
	Determine if a given character is a valid file separator for the host system.
Static Public Attributes
static const char	separator = FS
	The host system's file separator character.
static const char	validSeparators []
	A string containing all valid file separator characters for the host system.
static const char	separatorString [] = { File::separator, NUL }
	The host system's file separator character, as a string.
static const char *	eol = EOL
	The host system's end-of-line character sequence.
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.
Protected Member Functions
void	_init (FileHandle handle, bool seekable, bool readable, bool writable)
	Initialize the stream for use with an open file.
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 ( const String & path )

Construct a new File with the given path.

Parameters:

path

The path.

~File ( ) throw () [virtual]

Destructor.

Member Function Documentation

void _init	(	FileHandle	handle,
		bool	seekable,
		bool	readable,
		bool	writable
	)			`[protected, inherited]`

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.

void close ( IOMode mode = IOReadWrite ) throw () [virtual, inherited]

Close the stream for reading, writing, or both.

Parameters:

mode

The close mode.

Reimplemented in StreamPipe, and StreamSocket.

bool copy	(	const String &	oldFile,
		const String &	newFile
	)			throw () `[static]`

Copy a file to another file.

Parameters:

	oldFile	The source file.
	newFile	The target file.

Returns:: true on success, false otherwise.

bool createLink	(	const String &	oldPath,
		const String &	newPath,
		bool	hardLink = `false`
	)			throw () `[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.

bool exists ( const String & path ) throw () [static]

Test a file for existence.

Parameters:

path

The path of the file.

Returns:: true if the file exists, false otherwise.

bool exists ( ) const throw ()

Test if the file exists.

bool getAttributes	(	const String &	path,
		FileAttributes &	attrs
	)			throw () `[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.

size_t getDiskBlockSize ( const String & path ) throw () [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.

uint64_t getDiskFreeSpace ( const String & path ) throw () [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.

void getFileSystemRoots	(	StringVec &	roots,
		bool	localOnly = `true`
	)			throw () `[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.

String getPath ( ) const [inline]

Get the pathname for the file.

bool getPermissions	(	const String &	path,
		Permissions &	perm
	)			throw () `[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.

bool getPermissions ( Permissions & perm ) throw ()

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.

int64_t getSize ( const String & path ) throw () [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.

int64_t getSize ( ) throw (IOException)

Get the size of the file.

Returns:: The size of the file.

Exceptions:

IOException

If an error occurs.

timespan_ms_t getTimeout ( ) const throw () [inline, inherited]

Get the stream I/O timeout, in milliseconds.

bool isDirectory ( const String & path ) throw () [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.

bool isDirectory ( ) const throw ()

Test if the file is a directory.

bool isFile ( const String & path ) throw () [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.

bool isFile ( ) const throw ()

Test if the file is a plain file.

bool isFullDuplex ( ) const throw () [inline, inherited]

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

bool isHalfDuplex ( ) const throw () [inline, inherited]

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

bool isOpen ( ) const throw () [inline, inherited]

Test if the stream is open.

bool isPipe ( const String & path ) throw () [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.

bool isPipe ( ) const throw ()

Test if the file is a pipe or socket.

bool isReadable ( ) const throw () [inline, inherited]

Test if the stream can be read from.

bool isSeekable ( ) const throw () [inline, inherited]

Test if the stream supports seeking.

bool isSymLink ( const String & path ) throw () [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.

bool isSymLink ( ) const throw ()

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.

bool isValidSeparator ( char c ) throw () [static]

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

bool isWritable ( ) const throw () [inline, inherited]

Test if the stream can be written to.

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

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.

bool makeDirectory	(	const String &	path,
		bool	createAll = `false`,
		const Permissions &	perm = `Permissions::defaultDirPerms`
	)			throw () `[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.

bool move	(	const String &	oldFile,
		const String &	newFile
	)			throw () `[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.

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

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.

size_t read	(	MemoryBlock *	vec,
		uint_t	count
	)			throw (IOException) `[virtual, inherited]`

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.

size_t read	(	ByteBuffer &	buffer,
		int64_t	offset,
		AsyncIOTask &	task
	)			throw (IOException) `[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.

Reimplemented in StreamSocket.

size_t read	(	byte_t *	buffer,
		size_t	buflen,
		int64_t	offset,
		AsyncIOTask &	task
	)			throw (IOException) `[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.

Reimplemented in StreamSocket.

size_t read	(	byte_t *	buffer,
		size_t	buflen
	)			throw (IOException) `[virtual, inherited]`

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.

size_t read	(	Buffer< T > &	buffer,
		size_t &	partial
	)			throw (IOException) `[inline, inherited]`

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.

size_t read ( CharBuffer & buffer ) throw (IOException) [virtual, inherited]

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.

size_t read ( ByteBuffer & buffer ) throw (IOException) [virtual, inherited]

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.

size_t readFully	(	byte_t *	buffer,
		size_t	buflen
	)			throw (IOException) `[virtual, inherited]`

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.

size_t readFully	(	Buffer< T > &	buffer,
		size_t &	partial
	)			throw (IOException) `[inline, inherited]`

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.

size_t readFully	(	CharBuffer &	buffer,
		size_t	count = `0`
	)			throw (IOException) `[virtual, inherited]`

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.

size_t readFully	(	ByteBuffer &	buffer,
		size_t	count = `0`
	)			throw (IOException) `[virtual, inherited]`

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.

bool readSymLink ( String & path ) throw () [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.

bool remove ( const String & path ) throw () [static]

Remove a file.

Parameters:

path

The path to the file.

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

bool remove ( ) throw ()

Remove the file.

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

bool removeDirectory ( const String & path ) throw () [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.

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.

String removeTrailingSeparators ( const String & path ) throw () [static]

Remove trailing file separators from a file path.

Parameters:

path

The path.

Returns:: The path with trailing file separators removed.

bool rename	(	const String &	oldName,
		const String &	newName
	)			throw () `[static]`

Rename a file.

Parameters:

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

Returns:: true on success, false otherwise.

bool resolveSymLink ( String & path ) throw () [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.

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.

int64_t seek	(	int64_t	offset,
		SeekMode	mode = `SeekAbsolute`
	)			throw (IOException) `[virtual, inherited]`

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.

void setCreationMask ( const Permissions & perm ) throw () [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.

bool setPermissions	(	const String &	path,
		const Permissions &	perm
	)			throw () `[static]`

Set the permissions on a file.

Parameters:

	path	The file.
	perm	The Permissions to set.

Returns:: true on success, false otherwise.

bool setPermissions ( const Permissions & perm ) throw ()

Set the file permissions.

Parameters:

perm

The Permissions to set.

Returns:: true on success, false otherwise.

void setTimeout ( timespan_ms_t timeout ) throw (IOException) [virtual, inherited]

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 SerialPort, and StreamSocket.

int64_t tell ( ) throw (IOException) [virtual, inherited]

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.

bool touch ( const String & path ) throw () [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.

bool touch ( ) throw ()

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.

void truncate ( uint64_t size = 0 ) throw (IOException)

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.

bool unlockRange	(	uint64_t	start,
		uint64_t	length
	)			throw ()

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.

size_t write	(	const MemoryBlock *	vec,
		uint_t	count
	)			throw (IOException) `[virtual, inherited]`

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.

size_t write	(	const byte_t *	buffer,
		size_t	buflen
	)			throw (IOException) `[virtual, inherited]`

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.

size_t write	(	Buffer< T > &	buffer,
		size_t &	partial
	)			throw (IOException) `[inline, inherited]`

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.

size_t write ( CharBuffer & buffer ) throw (IOException) [virtual, inherited]

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.

size_t write ( ByteBuffer & buffer ) throw (IOException) [virtual, inherited]

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.

size_t write	(	ByteBuffer &	buffer,
		int64_t	offset,
		AsyncIOTask &	task
	)			throw (IOException) `[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.

Reimplemented in StreamSocket.

size_t write	(	const byte_t *	buffer,
		size_t	buflen,
		int64_t	offset,
		AsyncIOTask &	task
	)			throw (IOException) `[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.

Reimplemented in StreamSocket.

size_t writeFully	(	const byte_t *	buffer,
		size_t	buflen
	)			throw (IOException) `[virtual, inherited]`

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.

size_t writeFully	(	Buffer< T > &	buffer,
		size_t &	partial
	)			throw (IOException) `[inline, inherited]`

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.

size_t writeFully ( CharBuffer & buffer ) throw (IOException) [virtual, inherited]

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.

size_t writeFully ( ByteBuffer & buffer ) throw (IOException) [virtual, inherited]

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.

Member Data Documentation

String _name [protected]

const char * eol = EOL [static]

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

const uint_t MAX_IOBLOCK_COUNT = 16 [static, inherited]

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

const char separator = FS [static]

The host system's file separator character.

const char separatorString = { File::separator, NUL } [static]

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

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:

File Class Reference

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation