casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
casacore::File Class Reference

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

#include <File.h>

Inheritance diagram for casacore::File:
casacore::Directory casacore::RegularFile casacore::SymLink

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 ()
 
Fileoperator= (const File &that)
 Assignment (copy semantics). More...
 
const Pathpath () 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< uIntuniqueSeqnr_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

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

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

casacore::File::File ( )

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

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

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

casacore::File::File ( const String path)
casacore::File::File ( const File that)

Copy constructor (copy semantics).

virtual casacore::File::~File ( )
virtual

Member Function Documentation

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.

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.

Bool casacore::File::canCreate ( ) const

Check if a file can be created.

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

Bool casacore::File::exists ( ) const

Check if the file exists.

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.

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.

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

Get the lstat of a file.

Throw an exception when it fails.

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.

long casacore::File::groupID ( ) const

Return the groupID of the file.

Bool casacore::File::isBlockSpecial ( ) const

Check if the file is a block special file.

Bool casacore::File::isCharacterSpecial ( ) const

Check if the file is a character special file.

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.

Referenced by casa::SynthesisNormalizerMixin< T >::setup_normalizer().

Bool casacore::File::isExecutable ( ) const

Check if the file is executable.

Bool casacore::File::isPipe ( ) const

Check if the file is a pipe.

Bool casacore::File::isReadable ( ) const

Check if the file is readable.

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.

Bool casacore::File::isSocket ( ) const

Check if the file is a socket.

Bool casacore::File::isSymLink ( ) const

Check if the file is a symbolic link.

Bool casacore::File::isWritable ( ) const

Check if the file is writable.

uInt casacore::File::modifyTime ( ) const

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

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.

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.

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"
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"
File& casacore::File::operator= ( const File that)

Assignment (copy semantics).

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

Returns the pathname of the file.

Definition at line 310 of file File.h.

References itsPath.

uInt casacore::File::readPermissions ( ) const

Return the permissions as a decimal value.

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.

void casacore::File::setPermissions ( uInt  permissions)

Set permission with perm.

Perm is an octal value.

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::Directory, and casacore::RegularFile.

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.

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

void casacore::File::touch ( uInt  time)

Update access time and modification time of a file.

void casacore::File::touch ( )

Update access time and modification time of a file.

This function updates the file with the current time.

long casacore::File::userID ( ) const

Return the userID of the file.

Member Data Documentation

Path casacore::File::itsPath
private

Full pathname of the file.

Definition at line 304 of file File.h.

Referenced by path().

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: