casacore::File Class Reference

More...

#include <File.h>

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. More...
	File (const Path &path)
	Construct a File object whose Path is set to the given Path. More...
	File (const String &path)
	File (const File &that)
	Copy constructor (copy semantics). More...
virtual	~File ()
File &	operator= (const File &that)
	Assignment (copy semantics). More...
const Path &	path () const
	Returns the pathname of the file. More...
Bool	isRegular (Bool followSymLink=True) const
	Check if the file is a regular file. More...
Bool	isDirectory (Bool followSymLink=True) const
	Check if the file is a directory. More...
Bool	isSymLink () const
	Check if the file is a symbolic link. More...
Bool	isPipe () const
	Check if the file is a pipe. More...
Bool	isCharacterSpecial () const
	Check if the file is a character special file. More...
Bool	isBlockSpecial () const
	Check if the file is a block special file. More...
Bool	isSocket () const
	Check if the file is a socket. More...
Bool	exists () const
	Check if the file exists. More...
Bool	isReadable () const
	Check if the file is readable. More...
Bool	isWritable () const
	Check if the file is writable. More...
Bool	isExecutable () const
	Check if the file is executable. More...
Bool	canCreate () const
	Check if a file can be created. More...
long	userID () const
	Return the userID of the file. More...
long	groupID () const
	Return the groupID of the file. More...
virtual Int64	size () const
	Return the size of the file. More...
uInt	readPermissions () const
	Return the permissions as a decimal value. More...
void	setPermissions (uInt permissions)
	Set permission with perm. More...
void	touch (uInt time)
	Update access time and modification time of a file. More...
void	touch ()
	Update access time and modification time of a file. More...
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. More...
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. More...
uInt	modifyTime () const
	Return the time when the file was last modified in seconds since 00:00:00 GMT Jan 1, 1970. More...
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. More...
uInt	statusChangeTime () const
	Return the time when the file status was last changed in seconds since 00:00:00 GMT Jan 1, 1970. More...
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 More...
FileWriteStatus	getWriteStatus () const
	get write status of the file. More...
String	getFSType () const
	Return the filesystem type. More...

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: More...
static Path	newUniqueName (const String &directory)
	Create a new unique filename without a prefix. More...

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. More...
void	checkTarget (Path &targetName, Bool overwrite, Bool forDirectory=False) const
	Check if the new path for a copy or move is valid. More...

Private Member Functions
int	mylstat (const char *path, void *buf) const
	Define a function for lstat. More...
void	getstat (void *buf) const
	Get the lstat of this file. More...
void	getstat (const File &file, void *buf) const
	Get the lstat of a file. More...

Private Attributes
Path	itsPath
	Full pathname of the file. More...

Static Private Attributes
static std::atomic< uInt >	uniqueSeqnr_p
	A sequence number to generate unique file names. More...

Detailed Description

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

Review Status

Reviewed By:

UNKNOWN

Date Reviewed:

before2004/08/25

Intended use:

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 101 of file File.h.

Member Enumeration Documentation

FileWriteStatus

enum casacore::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 105 of file File.h.

Constructor & Destructor Documentation

File() [1/4]

casacore::File::File

(

)

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

File() [2/4]

casacore::File::File

(

const Path &

path

)

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

File() [3/4]

casacore::File::File

(

const String &

path

)

File() [4/4]

casacore::File::File

(

const File &

that

)

Copy constructor (copy semantics).

~File()

virtual casacore::File::~File ( )

virtual

Member Function Documentation

accessTime()

uInt casacore::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.

accessTimeString()

String casacore::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.

canCreate()

Bool casacore::File::canCreate

(

)

const

Check if a file can be created.

checkTarget()

void casacore::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).

exists()

Bool casacore::File::exists

(

)

const

Check if the file exists.

getFSType()

String casacore::File::getFSType

(

)

const

Return the filesystem type.

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

getstat() [1/2]

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

private

Get the lstat of a file.

Throw an exception when it fails.

getstat() [2/2]

void casacore::File::getstat ( void *  buf ) const

inlineprivate

Get the lstat of this file.

Throw an exception when it fails.

Definition at line 315 of file File.h.

getWriteStatus()

FileWriteStatus casacore::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.

groupID()

long casacore::File::groupID

(

)

const

Return the groupID of the file.

isBlockSpecial()

Bool casacore::File::isBlockSpecial

(

)

const

Check if the file is a block special file.

isCharacterSpecial()

Bool casacore::File::isCharacterSpecial

(

)

const

Check if the file is a character special file.

isDirectory()

Bool casacore::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.

isExecutable()

Bool casacore::File::isExecutable

(

)

const

Check if the file is executable.

isPipe()

Bool casacore::File::isPipe

(

)

const

Check if the file is a pipe.

isReadable()

Bool casacore::File::isReadable

(

)

const

Check if the file is readable.

isRegular()

Bool casacore::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.

isSocket()

Bool casacore::File::isSocket

(

)

const

Check if the file is a socket.

isSymLink()

Bool casacore::File::isSymLink

(

)

const

Check if the file is a symbolic link.

isWritable()

Bool casacore::File::isWritable

(

)

const

Check if the file is writable.

modifyTime()

uInt casacore::File::modifyTime

(

)

const

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

modifyTimeString()

String casacore::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.

mylstat()

int casacore::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.

newUniqueName() [1/2]

static Path casacore::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"

newUniqueName() [2/2]

static Path casacore::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"

operator=()

File& casacore::File::operator=

(

const File &

that

)

Assignment (copy semantics).

path()

const Path & casacore::File::path ( ) const

inline

Returns the pathname of the file.

Definition at line 310 of file File.h.

References itsPath.

readPermissions()

uInt casacore::File::readPermissions

(

)

const

Return the permissions as a decimal value.

removeSymLinks()

void casacore::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.

setPermissions()

void casacore::File::setPermissions

(

uInt

permissions

)

Set permission with perm.

Perm is an octal value.

size()

virtual Int64 casacore::File::size ( ) const

virtual

Return the size of the file.

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

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

statusChangeTime()

uInt casacore::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.

statusChangeTimeString()

String casacore::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

touch() [1/2]

void casacore::File::touch

(

)

Update access time and modification time of a file.

This function updates the file with the current time.

touch() [2/2]

void casacore::File::touch

(

uInt

time

)

Update access time and modification time of a file.

userID()

long casacore::File::userID

(

)

const

Return the userID of the file.

Member Data Documentation

itsPath

Path casacore::File::itsPath

private

Full pathname of the file.

Definition at line 304 of file File.h.

Referenced by path().

uniqueSeqnr_p

std::atomic<uInt> casacore::File::uniqueSeqnr_p

staticprivate

A sequence number to generate unique file names.

Definition at line 306 of file File.h.

---

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

• casa/OS/File.h