File.h

Classes

File -- Class to get file information and a base for other file classes. (full description)

class File

Interface

Public Members
File()
File (const Path& path)
File (const String& path)
File (const File& that)
virtual ~File()
File& operator= (const File& that)
const Path& path() const
Bool isRegular (Bool followSymLink = True) const
Bool isDirectory (Bool followSymLink = True) const
Bool isSymLink() const
Bool isPipe() const
Bool isCharacterSpecial() const
Bool isBlockSpecial() const
Bool isSocket() const
Bool exists() const
Bool isReadable() const
Bool isWritable() const
Bool isExecutable() const
Bool canCreate() const
long userID() const
long groupID() const
virtual Int64 size() const
uInt readPermissions() const
void setPermissions (uInt permissions)
void touch (uInt time)
void touch()
uInt accessTime() const
String accessTimeString() const
uInt modifyTime() const
String modifyTimeString() const
uInt statusChangeTime() const
String statusChangeTimeString() const
static Path newUniqueName (const String& directory, const String& prefix)
static Path newUniqueName (const String& directory)
Protected Members
void removeSymLinks()
void checkTarget (Path& targetName, Bool overwrite, Bool forDirectory = False) const
Private Members
int mylstat (const char* path, void* buf) const
void getstat (void* buf) const
void getstat (const File& file, void* buf) const

Description

Review Status

Reviewed By:
UNKNOWN
Date Reviewed:
before2004/08/25

Prerequisite

Etymology

'File' is used in a traditional sense.

Synopsis

The File class provides the primary functions needed by all kinds of files (directories, regular files, symbolic links, named pipes etc.). These shared functions serve mostly to return information about a particular file -- for instance, its type, its ownership, read, write and execute permissions, date of latest access and the path on secundary storage associated with this file. Every file object has, by definition, a Path object associated with it which defines the file name.

See also the derived classes RegularFile, Directory, and SymLink.
This class does not contain virtual functions, because a lot of functions have different parameters, e.g. 'create' for RegularFile has one parameter and 'create' for SymLink has two parameters.

It handles large files correctly.

Example

    File myFile("someFileName");
    if (myFile.exists()) {
	myFile.setPermissions(0644);
	if (myFile.isRegular()) {
	    cout << "this file is a regular file" << endl;
      }
    }
    else if (!myFile.exists()) {
	  if (!myFile.canCreate()){
	      cout << "cannot create this file" << endl;
	  } 
    }

Motivation

File systems operations are a notorious source of porting problems. The file class provides a standard interface for programmers to use.

Member Description

File()

Construct a File object whose Path is set to the current working directory.

File (const Path& path)
File (const String& path)

Construct a File object whose Path is set to the given Path.

File (const File& that)

Copy constructor (copy semantics).

virtual ~File()

File& operator= (const File& that)

Assignment (copy semantics).

const Path& path() const

Returns the pathname of the file.

Bool isRegular (Bool followSymLink = True) const

Check if the file is a regular file. If the boolean followSymLink is False a symbolic link will not be followed.

Bool isDirectory (Bool followSymLink = True) const

Check if the file is a directory. If the boolean followSymLink is False a symbolic link will not be followed.

Bool isSymLink() const

Check if the file is a symbolic link.

Bool isPipe() const

Check if the file is a pipe.

Bool isCharacterSpecial() const

Check if the file is a character special file.

Bool isBlockSpecial() const

Check if the file is a block special file.

Bool isSocket() const

Check if the file is a socket.

Bool exists() const

Check if the file exists.

Bool isReadable() const

Check if the file is readable.

Bool isWritable() const

Check if the file is writable.

Bool isExecutable() const

Check if the file is executable.

Bool canCreate() const

Check if a file can be created.

long userID() const

Return the userID of the file.

long groupID() const

Return the groupID of the file.

virtual Int64 size() const

Return the size of the file. If the file does not exist, an exception will be thrown.

uInt readPermissions() const

Return the permissions as a decimal value.

void setPermissions (uInt permissions)

Set permission with perm. Perm is an octal value.

void touch (uInt time)

Update access time and modification time of a file.

void touch()

Update access time and modification time of a file. This function updates the file with the current time.

uInt accessTime() const

Time related fucnctions: Return the time when the file was last accessed in seconds since 00:00:00 GMT Jan 1, 1970.

String accessTimeString() const

Return the time when the file was last accessed as a 26-characters String of the form: Thu Feb 3 13:40:11 1994\n\0.

uInt modifyTime() const

Return the time when the file was last modified in seconds since 00:00:00 GMT Jan 1, 1970.

String modifyTimeString() const

Return the time when the file was last modified as a 26-characters String of the form: Thu Feb 3 13:40:11 1994\n\0.

uInt statusChangeTime() const

Return the time when the file status was last changed in seconds since 00:00:00 GMT Jan 1, 1970. It is set both by writing and changing the file status information, such as changes of owner, group, link count, or mode.

String statusChangeTimeString() const

return the time when the file status was last changed as a 26-characters String of the form: Thu Feb 3 13:40:11 1994\n\0

static Path newUniqueName (const String& directory, const String& prefix)

Create a new unique path name in the specified directory, with the specified prefix and random trailing characters:

    p.newUniqueName ("./", "temp")  -->  "./tempAAA00xx32"
    p.newUniqueName ("/home/me", "diary")  -->  "/home/me/diaryAAA00xxb0"

static Path newUniqueName (const String& directory)

Create a new unique filename without a prefix. As above, but all the characters in the filename are random:

    p.newUniqueName ("./")  -->  "./AAA00xx32"
    p.newUniqueName ("/home/me")  -->  "/home/me/AAA00xxb0"

void removeSymLinks()

This function is used by RegularFile and Directory to remove all the links which, when followed, ultimately resolve to a Directory or a RegularFile. For example, A->B, B->C, C->D and D points to a regular file. When remove() is called for a regular file A, that function uses removeLinks() to remove A, B, C and D.

void checkTarget (Path& targetName, Bool overwrite, Bool forDirectory = False) const

Check if the new path for a copy or move is valid. An exception is thrown if:
- the target directory is not writable
- or the target file already exists and overwrite==False
- or the target file already exists and is not writable
When the targetName represents a directory, the basename of the file is appended to it. This is done to cover the case where the source is a symlink to a file. In that case the target will get the basename of the symlink and not the the basename of the file pointed to. This is not done when forDirectory==True (which is used by class Directory).

int mylstat (const char* path, void* buf) const

Define a function for lstat. This is necessary since SunOS4.1.x prototypes lstat() with a first argument of type (char*), while Solaris (and presumably all other reasonable OS's) prototype it with a first argument of type (const char*). Since lstat() does not change its first argument, it is safe to convert our const variable to a non-const one so that we can call lstat() successfully.
It is also useful to be able to pass the buffer as void*. In that way the 32-bit or 64-bit file details are only needed in the cc file.

void getstat (void* buf) const

Get the lstat of this file. Throw an exception when it fails.

void getstat (const File& file, void* buf) const

Get the lstat of a file. Throw an exception when it fails.