casa::File Class Reference

Class to get file information and a base for other file classes. More...

#include <File.h>

Inheritance diagram for casa::File:

List of all members.

Public Types
enum	FileWriteStatus {   OVERWRITABLE,   NOT_OVERWRITABLE,   CREATABLE,   NOT_CREATABLE }
Public Member Functions
	File ()
	Construct a File object whose Path is set to the current working directory.
	File (const Path &path)
	Construct a File object whose Path is set to the given Path.
	File (const String &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.
Bool	isDirectory (Bool followSymLink=True) const
	Check if the file is a directory.
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.
uInt	readPermissions () const
	Return the permissions as a decimal value.
void	setPermissions (uInt permissions)
	Set permission with perm.
void	touch (uInt time)
	Update access time and modification time of a file.
void	touch ()
	Update access time and modification time of a file.
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.
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.
uInt	statusChangeTime () const
	Return the time when the file status was last changed in seconds since 00:00:00 GMT Jan 1, 1970.
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
FileWriteStatus	getWriteStatus () const
	get write status of the file.
String	getFSType () const
	Return the filesystem type.
Static Public Member Functions
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:
static Path	newUniqueName (const String &directory)
	Create a new unique filename without a prefix.
Protected Member Functions
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.
void	checkTarget (Path &targetName, Bool overwrite, Bool forDirectory=False) const
	Check if the new path for a copy or move is valid.
Private Member Functions
int	mylstat (const char *path, void *buf) const
	Define a function for lstat.
void	getstat (void *buf) const
	Get the lstat of this file.
void	getstat (const File &file, void *buf) const
	Get the lstat of a file.
Private Attributes
Path	itsPath
	Full pathname of the file.
Static Private Attributes
static uInt	uniqueSeqnr_p
	A sequence number to generate unique file names.
static Mutex	theirMutex

---

Detailed Description

Class to get file information and a base for other file classes.

Review Status

Reviewed By:

UNKNOWN

Date Reviewed:

before2004/08/25

<h3>Intended use:</h3> Public interface

Prerequisite

• Basic knowledge of the UNIX file system
• Path

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.

Definition at line 102 of file File.h.

---

Member Enumeration Documentation

enum casa::File::FileWriteStatus

Enumerator:

OVERWRITABLE	file exists and can be overwritten
NOT_OVERWRITABLE	file exists but cannot be overwritten
CREATABLE	file does not exist and is creatable
NOT_CREATABLE	file does not exist but cannot be created

Definition at line 106 of file File.h.

---

Constructor & Destructor Documentation

casa::File::File

(

)

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

casa::File::File

(

const Path &

path

)

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

casa::File::File

(

const String &

path

)

casa::File::File

(

const File &

that

)

Copy constructor (copy semantics).

virtual casa::File::~File

(

)

[virtual]

---

Member Function Documentation

uInt casa::File::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 casa::File::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.

Bool casa::File::canCreate

(

)

const

Check if a file can be created.

void casa::File::checkTarget	(	Path &	targetName,
		Bool	overwrite,
		Bool	forDirectory = False
	)		const [protected]

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).

Bool casa::File::exists

(

)

const

Check if the file exists.

String casa::File::getFSType

(

)

const

Return the filesystem type.

If the file doesn't exsist crawl up the directory tree to find one that does.

void casa::File::getstat

(

void *

buf

)

const [inline, private]

Get the lstat of this file.

Throw an exception when it fails.

Definition at line 317 of file File.h.

void casa::File::getstat	(	const File &	file,
		void *	buf
	)		const [private]

Get the lstat of a file.

Throw an exception when it fails.

FileWriteStatus casa::File::getWriteStatus

(

)

const

get write status of the file.

OVERWRITABLE - file exists and can be overwritten NOT_OVERWRITABLE - file exists but cannot be overwritten CREATABLE - File does not exist and can be created NOT_CREATABLE - file does not exist and cannot be created.

long casa::File::groupID

(

)

const

Return the groupID of the file.

Bool casa::File::isBlockSpecial

(

)

const

Check if the file is a block special file.

Bool casa::File::isCharacterSpecial

(

)

const

Check if the file is a character special file.

Bool casa::File::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 casa::File::isExecutable

(

)

const

Check if the file is executable.

Bool casa::File::isPipe

(

)

const

Check if the file is a pipe.

Bool casa::File::isReadable

(

)

const

Check if the file is readable.

Bool casa::File::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 casa::File::isSocket

(

)

const

Check if the file is a socket.

Bool casa::File::isSymLink

(

)

const

Check if the file is a symbolic link.

Bool casa::File::isWritable

(

)

const

Check if the file is writable.

uInt casa::File::modifyTime

(

)

const

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

String casa::File::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.

int casa::File::mylstat	(	const char *	path,
		void *	buf
	)		const [private]

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.

static Path casa::File::newUniqueName	(	const String &	directory,
		const String &	prefix
	)		[static]

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 casa::File::newUniqueName

(

const String &

directory

)

[static]

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"

File& casa::File::operator=

(

const File &

that

)

Assignment (copy semantics).

const Path & casa::File::path

(

)

const [inline]

Returns the pathname of the file.

Definition at line 312 of file File.h.

References itsPath.

uInt casa::File::readPermissions

(

)

const

Return the permissions as a decimal value.

void casa::File::removeSymLinks

(

)

[protected]

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 casa::File::setPermissions

(

uInt

permissions

)

Set permission with perm.

Perm is an octal value.

virtual Int64 casa::File::size

(

)

const [virtual]

Return the size of the file.

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

Reimplemented in casa::Directory, and casa::RegularFile.

uInt casa::File::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 casa::File::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

void casa::File::touch

(

uInt

time

)

Update access time and modification time of a file.

void casa::File::touch

(

)

Update access time and modification time of a file.

This function updates the file with the current time.

long casa::File::userID

(

)

const

Return the userID of the file.

---

Member Data Documentation

Path casa::File::itsPath [private]

Full pathname of the file.

Definition at line 305 of file File.h.

Referenced by path().

Mutex casa::File::theirMutex [static, private]

Definition at line 308 of file File.h.

uInt casa::File::uniqueSeqnr_p [static, private]

A sequence number to generate unique file names.

Definition at line 307 of file File.h.

---

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

• casacore/casa/OS/File.h