This class represents a disk file. More...

#include <file.h>

Inheritance diagram for PFile:

Collaboration diagram for PFile:

Classes
struct	RotateInfo
	Information on how to rotate files. More...

Public Member Functions
Overrides from class PObject
Comparison	Compare (const PObject &obj) const
	Determine the relative rank of the two objects. More...

Overrides from class PChannel
virtual PString	GetName () const
	Get the platform and I/O channel type name of the channel. More...

virtual PBoolean	Read (void *buf, PINDEX len)
	Low level read from the file channel. More...

virtual PBoolean	Write (const void *buf, PINDEX len)
	Low level write to the file channel. More...

virtual PBoolean	Close ()
	Close the file channel. More...

Public Member Functions inherited from PChannel
PBoolean	SetErrorValues (Errors errorCode, int osError, ErrorGroup group=LastGeneralError)
	Set error values to those specified. More...

virtual PINDEX	HashFunction () const
	Calculate a hash value for use in sets and dictionaries. More...

virtual PBoolean	IsOpen () const
	Determine if the channel is currently open. More...

virtual P_INT_PTR	GetHandle () const
	Get the integer operating system handle for the channel. More...

FILE *	FDOpen (const char *mode)
	Re-open the device using the stdio library. More...

virtual PChannel *	GetBaseReadChannel () const
	Get the base channel of channel indirection using PIndirectChannel. More...

virtual PChannel *	GetBaseWriteChannel () const
	Get the base channel of channel indirection using PIndirectChannel. More...

virtual bool	CloseBaseReadChannel ()
	Close the base channel of channel indirection using PIndirectChannel. More...

virtual bool	CloseBaseWriteChannel ()
	Close the base channel of channel indirection using PIndirectChannel. More...

void	SetReadTimeout (const PTimeInterval &time)
	Set the timeout for read operations. More...

PTimeInterval	GetReadTimeout () const
	Get the timeout for read operations. More...

virtual PINDEX	GetLastReadCount () const
	Get the number of bytes read by the last Read() call. More...

virtual PINDEX	SetLastReadCount (PINDEX count)

virtual int	ReadChar ()
	Read a single character from the channel. More...

PBoolean	ReadBlock (void *buf, PINDEX len)
	Read len bytes into the buffer from the channel. More...

PString	ReadString (PINDEX len)
	Read `len` character into a string from the channel. More...

void	SetWriteTimeout (const PTimeInterval &time)
	Set the timeout for write operations to complete. More...

PTimeInterval	GetWriteTimeout () const
	Get the timeout for write operations to complete. More...

virtual PBoolean	Write (const void buf, PINDEX len, const void )
	Low level write to the channel with marker. More...

virtual PINDEX	GetLastWriteCount () const
	Get the number of bytes written by the last Write() call. More...

virtual PINDEX	SetLastWriteCount (PINDEX count)

PBoolean	WriteChar (int c)
	Write a single character to the channel. More...

PBoolean	WriteString (const PString &str)
	Write a string to the channel. More...

	~PChannel ()
	Close down the channel. More...

Errors	GetErrorCode (ErrorGroup group=NumErrorGroups) const
	Get normalised error code. More...

int	GetErrorNumber (ErrorGroup group=NumErrorGroups) const
	Get OS errro code. More...

virtual PString	GetErrorText (ErrorGroup group=NumErrorGroups) const
	Get error message description. More...

virtual bool	ReadAsync (AsyncContext &context)
	Begin an asynchronous read from channel. More...

virtual void	OnReadComplete (AsyncContext &context)
	User callback function for when a `ReadAsync()` call has completed or timed out. More...

virtual bool	WriteAsync (AsyncContext &context)
	Begin an asynchronous write from channel. More...

virtual void	OnWriteComplete (AsyncContext &context)
	User callback function for when a WriteAsync() call has completed or timed out. More...

virtual PBoolean	Shutdown (ShutdownValue option)
	Close one or both of the data streams associated with a channel. More...

virtual bool	SetLocalEcho (bool localEcho)
	Set local echo mode. More...

virtual bool	FlowControl (const void *flowData)
	Flow Control information Pass data to the channel for flowControl determination. More...

PBoolean	SetBufferSize (PINDEX newSize)
	Set the iostream buffer size for reads and writes. More...

PBoolean	SendCommandString (const PString &command)
	Send a command meta-string. More...

void	AbortCommandString ()
	Abort a command string that is in progress. More...

Public Member Functions inherited from PObject
__inline unsigned	GetTraceContextIdentifier () const
	Get PTRACE context identifier. More...

__inline void	SetTraceContextIdentifier (unsigned id)

__inline void	SetTraceContextIdentifier (const PObject &obj)

__inline void	SetTraceContextIdentifier (const PObject *obj)

__inline void	CopyTraceContextIdentifier (PObject &obj) const

__inline void	CopyTraceContextIdentifier (PObject *obj) const

virtual	~PObject ()

__inline const char *	GetClass () const

__inline bool	IsClass (const char *name) const

__inline const PObject *	PTraceObjectInstance () const

virtual PObject *	Clone () const
	Create a copy of the class on the heap. More...

template<class CLS >
CLS *	CloneAs () const
	As for Clone() but converts to specified type. More...

virtual Comparison	CompareObjectMemoryDirect (const PObject &obj) const
	Determine the byte wise comparison of two objects. More...

bool	operator== (const PObject &obj) const
	Compare the two objects. More...

bool	operator!= (const PObject &obj) const
	Compare the two objects. More...

bool	operator< (const PObject &obj) const
	Compare the two objects. More...

bool	operator> (const PObject &obj) const
	Compare the two objects. More...

bool	operator<= (const PObject &obj) const
	Compare the two objects. More...

bool	operator>= (const PObject &obj) const
	Compare the two objects. More...

virtual void	PrintOn (ostream &strm) const
	Output the contents of the object to the stream. More...

virtual void	ReadFrom (istream &strm)
	Input the contents of the object from the stream. More...

Protected Member Functions
virtual bool	InternalOpen (OpenMode mode, OpenOptions opts, PFileInfo::Permissions permissions)

Protected Member Functions inherited from PChannel
	PChannel (const PChannel &)

PChannel &	operator= (const PChannel &)

virtual PBoolean	ConvertOSError (P_INT_PTR libcReturnValue, ErrorGroup group=LastGeneralError)
	Convert an operating system error into platform independent error. More...

int	ReadCharWithTimeout (PTimeInterval &timeout)
	Read a character with specified timeout. More...

PBoolean	ReceiveCommandString (int nextChar, const PString &reply, PINDEX &pos, PINDEX start)

bool	CheckNotOpen ()

virtual int	os_errno () const

PBoolean	PXSetIOBlock (PXBlockType type, const PTimeInterval &timeout)

P_INT_PTR	GetOSHandleAsInt () const

int	PXClose ()

	PDECLARE_MUTEX (px_threadMutex)

	PDECLARE_MUTEX (px_writeMutex)

	PChannel ()
	Create the channel. More...

Protected Member Functions inherited from PObject
	PObject ()
	Constructor for PObject, made protected so cannot ever create one on its own. More...

Protected Attributes
PFilePath	m_path
	The fully qualified path name for the file. More...

bool	m_removeOnClose
	File is to be removed when closed. More...

Protected Attributes inherited from PChannel
PTimeInterval	readTimeout
	Timeout for read operations. More...

PTimeInterval	writeTimeout
	Timeout for write operations. More...

atomic< P_INT_PTR >	os_handle
	The operating system file handle return by standard open() function. More...

PThreadLocalStorage< Status >	m_status [NumErrorGroups+1]

PXBlockType	px_lastBlockType

PThread *	px_readThread

PThread *	px_writeThread

PThread *	px_selectThread [3]

PCriticalSection	px_selectMutex [3]

Protected Attributes inherited from PObject
unsigned	m_traceContextIdentifier

Construction
enum	OpenMode { ReadOnly, WriteOnly, ReadWrite }
	When a file is opened, it may restrict the access available to operations on the object instance. More...

	PFile ()
	Create a file object but do not open it. More...

	P_DECLARE_BITWISE_ENUM_EX (OpenOptions, 7,(NoOptions, MustExist, Create, Truncate, Exclusive, Temporary, DenySharedRead, DenySharedWrite), ModeDefault=-1)
	When a file is opened, a number of options may be associated with the open file. More...

	PFile (OpenMode mode, OpenOptions opts=ModeDefault)
	Create a unique temporary file name, and open the file in the specified mode and using the specified options. More...

	PFile (const PFilePath &name, OpenMode mode=ReadWrite, OpenOptions opts=ModeDefault)
	Create a file object with the specified name and open it in the specified mode and with the specified options. More...

	~PFile ()
	Close the file on destruction. More...

File manipulation functions
bool	Exists () const
	Check for file existance. More...

bool	Access (OpenMode mode)
	Check for file access modes. More...

bool	Touch (const PTime &accessTime=0)
	Set access & modification times for file. More...

bool	Touch (const PTime &accessTime, const PTime &modTime)

bool	Remove (bool force=false)
	Delete the current file. More...

bool	Rename (const PString &newname, bool force=false)
	Change the current files name. More...

bool	Copy (const PFilePath &newname, bool force=false, bool recurse=false)
	Make a copy of the current file. More...

bool	Move (const PFilePath &newname, bool force=false, bool recurse=false)
	Move the current file. More...

static bool	Exists (const PFilePath &name)
	Check for file existance. More...

static bool	Access (const PFilePath &name, OpenMode mode)
	Check for file access modes. More...

static bool	Touch (const PFilePath &name, const PTime &accessTime=0)
	Set access & modification times for file. More...

static bool	Touch (const PFilePath &name, const PTime &accessTime, const PTime &modTime)

static bool	Remove (const PFilePath &name, bool force=false)
	Delete the specified file. More...

static bool	Remove (const PString &name, bool force=false)

static bool	Rename (const PFilePath &oldname, const PString &newname, bool force=false)
	Change the specified files name. More...

static bool	Copy (const PFilePath &oldname, const PFilePath &newname, bool force=false, bool recurse=false)
	Make a copy of the specified file. More...

static bool	Move (const PFilePath &oldname, const PFilePath &newname, bool force=false, bool recurse=false)
	Move the specified file. More...

File channel functions
enum	FilePositionOrigin { Start = SEEK_SET, Current = SEEK_CUR, End = SEEK_END }
	Options for the origin in setting the file position. More...

const PFilePath &	GetFilePath () const
	Get the full path name of the file. More...

void	SetFilePath (const PString &path)
	Set the full path name of the file. More...

bool	Open (OpenMode mode=ReadWrite, OpenOptions opts=ModeDefault)
	Open the current file in the specified mode and with the specified options. More...

bool	Open (OpenMode mode, OpenOptions opts, PFileInfo::Permissions permissions)
	Open the specified file name in the specified mode and with the specified options and permissions. More...

bool	Open (const PFilePath &name, OpenMode mode=ReadWrite, OpenOptions opts=ModeDefault)
	Open the specified file name in the specified mode and with the specified options. More...

bool	Open (const PFilePath &name, OpenMode mode, OpenOptions opts, PFileInfo::Permissions permissions)
	Open the specified file name in the specified mode and with the specified options and permissions. More...

virtual off_t	GetLength () const
	Get the current size of the file. More...

virtual PBoolean	SetLength (off_t len)
	Set the size of the file, padding with 0 bytes if it would require expanding the file, or truncating it if being made shorter. More...

virtual PBoolean	SetPosition (off_t pos, FilePositionOrigin origin=Start)
	Set the current active position in the file for the next read or write operation. More...

virtual off_t	GetPosition () const
	Get the current active position in the file for the next read or write operation. More...

bool	IsEndOfFile () const
	Determine if the current file position is at the end of the file. More...

bool	GetInfo (PFileInfo &info)
	Get information (eg protection, timestamps) on the current file. More...

bool	SetPermissions (PFileInfo::Permissions permissions)
	Set permissions on the current file. More...

static bool	GetInfo (const PFilePath &name, PFileInfo &info)
	Get information (eg protection, timestamps) on the specified file. More...

static bool	SetPermissions (const PFilePath &name, PFileInfo::Permissions permissions)
	Set permissions on the specified file. More...

Additional Inherited Members
Public Types inherited from PChannel
enum	PXBlockType { PXReadBlock, PXWriteBlock, PXAcceptBlock, PXConnectBlock }

enum	Errors { NoError, NotFound, FileExists, DiskFull, AccessDenied, DeviceInUse, BadParameter, NoMemory, NotOpen, Timeout, Interrupted, BufferTooSmall, Miscellaneous, ProtocolFailure, Unavailable, NumNormalisedErrors }
	Normalised error codes. More...

enum	ErrorGroup { LastReadError, LastWriteError, LastGeneralError, NumErrorGroups }
	Error groups. More...

typedef PNotifierTemplate < PChannel::AsyncContext & >	AsyncNotifier

enum	ShutdownValue { ShutdownRead = 0, ShutdownWrite = 1, ShutdownReadAndWrite = 2 }

Public Types inherited from PObject
enum	Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
	Result of the comparison operation performed by the `Compare()` function. More...

Static Public Member Functions inherited from PChannel
static PString	GetErrorText (Errors lastError, int osError=0)
	Get error message description. More...

Static Public Member Functions inherited from PObject
static __inline void	CopyTraceContextIdentifier (PObject &to, const PObject &from)

static __inline void	CopyTraceContextIdentifier (PObject &to, const PObject *from)

static __inline void	CopyTraceContextIdentifier (PObject *to, const PObject &from)

static __inline void	CopyTraceContextIdentifier (PObject to, const PObject from)

static __inline const char *	Class ()

static __inline const PObject *	PTraceObjectInstance (const char *)

static __inline const PObject *	PTraceObjectInstance (const PObject *obj)

template<typename T >
static Comparison	Compare2 (T v1, T v2)
	Compare two types, returning Comparison type. More...

static Comparison	InternalCompareObjectMemoryDirect (const PObject obj1, const PObject obj2, PINDEX size)
	Internal function caled from CompareObjectMemoryDirect() More...

Detailed Description

This class represents a disk file.

This is a particular type of I/O channel that has certain attributes. All platforms have a disk file, though exact details of naming convertions etc may be different.

The basic model for files is that they are a named sequence of bytes that persists within a directory structure. The transfer of data to and from the file is made at a current position in the file. This may be set to random locations within the file.

Member Enumeration Documentation

enum PFile::FilePositionOrigin

Options for the origin in setting the file position.

Enumerator
Start	Set position relative to start of file.
Current	Set position relative to current file position.
End	Set position relative to end of file.

enum PFile::OpenMode

When a file is opened, it may restrict the access available to operations on the object instance.

A value from this enum is passed to the Open() function to set the mode.

Enumerator
ReadOnly	File can be read but not written.
WriteOnly	File can be written but not read.
ReadWrite	File can be both read and written.

Constructor & Destructor Documentation

PFile::PFile ( )

Create a file object but do not open it.

It does not initially have a valid file name. However, an attempt to open the file using the Open() function will generate a unique temporary file.

PFile::PFile	(	OpenMode	mode,
		OpenOptions	opts = `ModeDefault`
	)

Create a unique temporary file name, and open the file in the specified mode and using the specified options.

Note that opening a new, unique, temporary file name in ReadOnly mode will always fail. This would only be usefull in a mode and options that will create the file.

The PChannel::IsOpen() function may be used after object construction to determine if the file was successfully opened.

Parameters

mode	Mode in which to open the file.
opts	`OpenOptions` enum# for open operation.

PFile::PFile	(	const PFilePath &	name,
		OpenMode	mode = `ReadWrite`,
		OpenOptions	opts = `ModeDefault`
	)

Create a file object with the specified name and open it in the specified mode and with the specified options.

The PChannel::IsOpen() function may be used after object construction to determine if the file was successfully opened.

Parameters

name	Name of file to open.
mode	Mode in which to open the file.
opts	`OpenOptions` enum# for open operation.

PFile::~PFile ( )

Close the file on destruction.

Member Function Documentation

static bool PFile::Access	(	const PFilePath &	name,
		OpenMode	mode
	)

static

Check for file access modes.

Determine if the file specified may be opened in the specified mode. This would check the current access rights to the file for the mode. For example, for a file that is read only, using mode == ReadWrite would return false but mode == ReadOnly would return true.

Returns: true if a file open would succeed.

Parameters

name	Name of file to have its access checked.
mode	Mode in which the file open would be done.

bool PFile::Access ( OpenMode mode )

Check for file access modes.

Determine if the file path specification associated with the instance of the object may be opened in the specified mode. This would check the current access rights to the file for the mode. For example, for a file that is read only, using mode == ReadWrite would return false but mode == ReadOnly would return true.

Returns: true if a file open would succeed.

Parameters

mode	Mode in which the file open would be done.

virtual PBoolean PFile::Close ( )

virtual

Close the file channel.

Returns: true if close was OK.

Reimplemented from PChannel.

Reimplemented in PMemoryFile.

Comparison PFile::Compare ( const PObject & obj ) const

virtual

Determine the relative rank of the two objects.

This is essentially the string comparison of the PFilePath names of the files.

Returns: relative rank of the file paths.

Parameters

obj	Other file to compare against.

Reimplemented from PChannel.

Reimplemented in PMemoryFile.

static bool PFile::Copy	(	const PFilePath &	oldname,
		const PFilePath &	newname,
		bool	force = `false`,
		bool	recurse = `false`
	)

static

Make a copy of the specified file.

Returns: true if the file was renamed.

Parameters

oldname	Old name of the file.
newname	New name for the file.
force	Delete file if a destination exists with the same name.
recurse	Recursively create all intermediate sub-directories

bool PFile::Copy	(	const PFilePath &	newname,
		bool	force = `false`,
		bool	recurse = `false`
	)

Make a copy of the current file.

Returns: true if the file was renamed.

Parameters

newname	New name for the file.
force	Delete file if a destination exists with the same name.
recurse	Recursively create all intermediate sub-directories

static bool PFile::Exists ( const PFilePath & name )

static

Check for file existance.

Determine if the file specified actually exists within the platforms file system.

Returns: true if the file exists.

Parameters

name	Name of file to see if exists.

bool PFile::Exists ( ) const

Check for file existance.

Determine if the file path specification associated with the instance of the object actually exists within the platforms file system.

Returns: true if the file exists.

const PFilePath& PFile::GetFilePath ( ) const

Get the full path name of the file.

The PFilePath object describes the full file name specification for the particular platform.

Returns: the name of the file.

static bool PFile::GetInfo	(	const PFilePath &	name,
		PFileInfo &	info
	)

static

Get information (eg protection, timestamps) on the specified file.

Returns: true if the file info was retrieved.

Parameters

name	Name of file to get the information on.
info	`PFileInfo` structure to receive the information.

bool PFile::GetInfo ( PFileInfo & info )

Get information (eg protection, timestamps) on the current file.

Returns: true if the file info was retrieved.

Parameters

info	`PFileInfo` structure to receive the information.

virtual off_t PFile::GetLength ( ) const

virtual

Get the current size of the file.

Returns: length of file in bytes.

Reimplemented in PMemoryFile.

virtual PString PFile::GetName ( ) const

virtual

Get the platform and I/O channel type name of the channel.

For example, it would return the filename in PFile type channels.

Returns: the name of the channel.

Implements PChannel.

virtual off_t PFile::GetPosition ( ) const

virtual

Get the current active position in the file for the next read or write operation.

Returns: current file position relative to start of file.

Reimplemented in PMemoryFile.

virtual bool PFile::InternalOpen	(	OpenMode	mode,
		OpenOptions	opts,
		PFileInfo::Permissions	permissions
	)

protectedvirtual

Reimplemented in PMemoryFile.

bool PFile::IsEndOfFile ( ) const

Determine if the current file position is at the end of the file.

If this is true then any read operation will fail.

Returns: true if at end of file.

static bool PFile::Move	(	const PFilePath &	oldname,
		const PFilePath &	newname,
		bool	force = `false`,
		bool	recurse = `false`
	)

static

Move the specified file.

This will move the file from one position in the directory hierarchy to another position. The actual operation is platform dependent but the reslt is the same. For instance, for Unix, if the move is within a file system then a simple rename is done, if it is across file systems then a copy and a delete is performed.

Returns: true if the file was moved.

Parameters

oldname	Old path and name of the file.
newname	New path and name for the file.
force	Delete file if a destination exists with the same name.
recurse	Recursively create all intermediate sub-directories

bool PFile::Move	(	const PFilePath &	newname,
		bool	force = `false`,
		bool	recurse = `false`
	)

Move the current file.

This will move the file from one position in the directory hierarchy to another position. The actual operation is platform dependent but the reslt is the same. For instance, for Unix, if the move is within a file system then a simple rename is done, if it is across file systems then a copy and a delete is performed.

Returns: true if the file was moved.

Parameters

newname	New path and name for the file.
force	Delete file if a destination exists with the same name.
recurse	Recursively create all intermediate sub-directories

bool PFile::Open	(	OpenMode	mode = `ReadWrite`,
		OpenOptions	opts = `ModeDefault`
	)

Open the current file in the specified mode and with the specified options.

If the file object already has an open file then it is closed.

If there has not been a filename attached to the file object (via SetFilePath(), the name parameter or a previous open) then a new unique temporary filename is generated.

Returns: true if the file was successfully opened.

Parameters

mode	Mode in which to open the file.
opts	Options for open operation.

bool PFile::Open	(	OpenMode	mode,
		OpenOptions	opts,
		PFileInfo::Permissions	permissions
	)

Open the specified file name in the specified mode and with the specified options and permissions.

If the file object already has an open file then it is closed.

Returns: true if the file was successfully opened.

Parameters

mode	Mode in which to open the file.
opts	`OpenOptions` enum# for open operation.
permissions	Permission for file if created

bool PFile::Open	(	const PFilePath &	name,
		OpenMode	mode = `ReadWrite`,
		OpenOptions	opts = `ModeDefault`
	)

Open the specified file name in the specified mode and with the specified options.

If the file object already has an open file then it is closed.

Returns: true if the file was successfully opened.

Parameters

name	Name of file to open.
mode	Mode in which to open the file.
opts	`OpenOptions` enum# for open operation.

bool PFile::Open	(	const PFilePath &	name,
		OpenMode	mode,
		OpenOptions	opts,
		PFileInfo::Permissions	permissions
	)

Open the specified file name in the specified mode and with the specified options and permissions.

If the file object already has an open file then it is closed.

Returns: true if the file was successfully opened.

Parameters

name	Name of file to open.
mode	Mode in which to open the file.
opts	`OpenOptions` enum# for open operation.
permissions	Permission for file if created

PFile::P_DECLARE_BITWISE_ENUM_EX	(	OpenOptions	,
		7	,
		(NoOptions, MustExist, Create, Truncate, Exclusive, Temporary, DenySharedRead, DenySharedWrite)	,
		ModeDefault	= `-1`
	)

When a file is opened, a number of options may be associated with the open file.

These describe what action to take on opening the file and what to do on closure. A value from this enum is passed to the Open() function to set the options.

The ModeDefault option will use the following values:

ReadOnly MustExist
WriteOnly Create | Truncate
ReadWrite Create

virtual PBoolean PFile::Read	(	void *	buf,
		PINDEX	len
	)

virtual

Low level read from the file channel.

The read timeout is ignored for file I/O. The GetLastReadCount() function returns the actual number of bytes read.

The GetErrorCode() function should be consulted after Read() returns false to determine what caused the failure.

Returns: true indicates that at least one character was read from the channel. false means no bytes were read due to timeout or some other I/O error.

Parameters

buf	Pointer to a block of memory to receive the read bytes.
len	Maximum number of bytes to read into the buffer.

Reimplemented from PChannel.

Reimplemented in PMemoryFile.

static bool PFile::Remove	(	const PFilePath &	name,
		bool	force = `false`
	)

static

Delete the specified file.

If force is false and the file is protected against being deleted then the function fails. If force is true then the protection is ignored. What constitutes file deletion protection is platform dependent, eg on DOS is the Read Only attribute and on a Novell network it is a Delete trustee right. Some protection may not be able to overridden with the force parameter at all, eg on a Unix system and you are not the owner of the file.

Returns: true if the file was deleted.

Parameters

name	Name of file to delete.
force	Force deletion even if file is protected.

static bool PFile::Remove	(	const PString &	name,
		bool	force = `false`
	)

static

Parameters

name	Name of file to delete.
force	Force deletion even if file is protected.

bool PFile::Remove ( bool force = false )

Delete the current file.

If force is false and the file is protected against being deleted then the function fails. If force is true then the protection is ignored. What constitutes file deletion protection is platform dependent, eg on DOS is the Read Only attribute and on a Novell network it is a Delete trustee right. Some protection may not be able to overridden with the force parameter at all, eg on a Unix system and you are not the owner of the file.

Returns: true if the file was deleted.

Parameters

force Force deletion even if file is protected.

static bool PFile::Rename	(	const PFilePath &	oldname,
		const PString &	newname,
		bool	force = `false`
	)

static

Change the specified files name.

This does not move the file in the directory hierarchy, it only changes the name of the directory entry.

The newname parameter must consist only of the file name part, as returned by the PFilePath::GetFileName() function. Any other file path parts will cause an error.

The first form uses the file path specification associated with the instance of the object. The name within the instance is changed to the new name if the function succeeds. The second static function uses an arbitrary file specified by name.

Returns: true if the file was renamed.

Parameters

oldname	Old name of the file.
newname	New name for the file.
force	Delete file if a destination exists with the same name.

bool PFile::Rename	(	const PString &	newname,
		bool	force = `false`
	)

Change the current files name.

This does not move the file in the directory hierarchy, it only changes the name of the directory entry.

The newname parameter must consist only of the file name part, as returned by the PFilePath::GetFileName() function. Any other file path parts will cause an error.

The first form uses the file path specification associated with the instance of the object. The name within the instance is changed to the new name if the function succeeds. The second static function uses an arbitrary file specified by name.

Returns: true if the file was renamed.

Parameters

newname	New name for the file.
force	Delete file if a destination exists with the same name.

void PFile::SetFilePath ( const PString & path )

Set the full path name of the file.

The PFilePath object describes the full file name specification for the particular platform.

Parameters

path	New file path.

virtual PBoolean PFile::SetLength ( off_t len )

virtual

Set the size of the file, padding with 0 bytes if it would require expanding the file, or truncating it if being made shorter.

Returns: true if the file size was changed to the length specified.

Reimplemented in PMemoryFile.

static bool PFile::SetPermissions	(	const PFilePath &	name,
		PFileInfo::Permissions	permissions
	)

static

Set permissions on the specified file.

Returns: true if the file was renamed.

Parameters

name	Name of file to change the permission of.
permissions	New permissions mask for the file.

bool PFile::SetPermissions ( PFileInfo::Permissions permissions )

Set permissions on the current file.

Returns: true if the file was renamed.

Parameters

permissions New permissions mask for the file.

virtual PBoolean PFile::SetPosition	(	off_t	pos,
		FilePositionOrigin	origin = `Start`
	)

virtual

Set the current active position in the file for the next read or write operation.

The pos variable is a signed number which is added to the specified origin. For origin == PFile::Start only positive values for pos are meaningful. For origin == PFile::End only negative values for pos are meaningful.

Returns: true if the new file position was set.

Parameters

pos	New position to set.
origin	Origin for position change.

Reimplemented in PMemoryFile.

static bool PFile::Touch	(	const PFilePath &	name,
		const PTime &	accessTime = `0`
	)

static

Set access & modification times for file.

If accessTime or modTime is invalid then current time is used for that time. If the modTime is not present it is set to the same as the accessTime.

Returns: true if file times changed.

Parameters

name	Name of file to have its access time changed.
accessTime	Time to set access time to.

static bool PFile::Touch	(	const PFilePath &	name,
		const PTime &	accessTime,
		const PTime &	modTime
	)

static

Parameters

name	Name of file to have its access time changed.
accessTime	Time to set access time to.
modTime	Time to set modification time to.

bool PFile::Touch ( const PTime & accessTime = 0 )

Set access & modification times for file.

Returns: true if file times changed.

Parameters

accessTime Time to set access time to.

bool PFile::Touch	(	const PTime &	accessTime,
		const PTime &	modTime
	)

Parameters

accessTime	Time to set access time to.
modTime	Time to set modification time to.

virtual PBoolean PFile::Write	(	const void *	buf,
		PINDEX	len
	)

virtual

Low level write to the file channel.

The write timeout is ignored for file I/O. The GetLastWriteCount() function returns the actual number of bytes written.

The GetErrorCode() function should be consulted after Write() returns false to determine what caused the failure.

Returns: true if at least len bytes were written to the channel.

Parameters

buf	Pointer to a block of memory to write.
len	Number of bytes to write.

Reimplemented from PChannel.

Reimplemented in PMemoryFile.

Member Data Documentation

PFilePath PFile::m_path

protected

The fully qualified path name for the file.

bool PFile::m_removeOnClose

protected

File is to be removed when closed.

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

file.h

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Construction

File manipulation functions

File channel functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation