casacore
File.h
Go to the documentation of this file.
1 //# File.h: Class to get file information and a base for other file classes
2 //# Copyright (C) 1993,1994,1995,1996,2000,2003
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef CASA_FILE_H
29 #define CASA_FILE_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/OS/Path.h>
34 #include <casacore/casa/BasicSL/String.h>
35 #include <atomic>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 // <summary>
40 // Class to get file information and a base for other file classes.
41 // </summary>
42 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
43 // </reviewed>
44 
45 // <use visibility=export>
46 
47 // <prerequisite>
48 // <li> Basic knowledge of the UNIX file system
49 // <li> <linkto class=Path>Path</linkto>
50 // </prerequisite>
51 
52 // <etymology>
53 // 'File' is used in a traditional sense.
54 // </etymology>
55 
56 // <synopsis>
57 // The File class provides the primary functions needed by all kinds of
58 // files (directories, regular files, symbolic links, named pipes etc.).
59 // These shared functions serve mostly to return information about a
60 // particular file -- for instance, its type, its ownership, read, write
61 // and execute permissions, date of latest access and the path on secundary
62 // storage associated with this file. Every file object has, by definition,
63 // a <linkto class=Path>Path</linkto> object associated with it which
64 // defines the file name.
65 // <p>
66 // See also the derived classes
67 // <linkto class=RegularFile>RegularFile</linkto>,
68 // <linkto class=Directory>Directory</linkto>, and
69 // <linkto class=SymLink>SymLink</linkto>.
70 // <br>
71 // This class does not contain virtual functions, because a lot of functions
72 // have different parameters, e.g. 'create' for RegularFile has one parameter
73 // and 'create' for SymLink has two parameters.
74 //
75 // It handles large files correctly.
76 // </synopsis>
77 
78 // <example>
79 // <srcblock>
80 // File myFile("someFileName");
81 // if (myFile.exists()) {
82 // myFile.setPermissions(0644);
83 // if (myFile.isRegular()) {
84 // cout << "this file is a regular file" << endl;
85 // }
86 // }
87 // else if (!myFile.exists()) {
88 // if (!myFile.canCreate()){
89 // cout << "cannot create this file" << endl;
90 // }
91 // }
92 // </srcblock>
93 // </example>
94 
95 // <motivation>
96 // File systems operations are a notorious source of porting problems.
97 // The file class provides a standard interface for programmers to use.
98 // </motivation>
99 
100 
101 class File
102 {
103 public:
104 
106  // file exists and can be overwritten
108  // file exists but cannot be overwritten
110  // file does not exist and is creatable
112  // file does not exist but cannot be created
114  };
115 
116 
117  // Construct a File object whose Path is set to the current working
118  // directory.
119  File();
120 
121  // Construct a File object whose Path is set to the given Path.
122  // <group>
123  File (const Path& path);
124  File (const String& path);
125  // </group>
126 
127  // Copy constructor (copy semantics).
128  File (const File& that);
129 
130  virtual ~File();
131 
132  // Assignment (copy semantics).
133  File& operator= (const File& that);
134 
135  // Returns the pathname of the file.
136  const Path& path() const;
137 
138  // Check if the file is a regular file. If the boolean followSymLink is
139  // False a symbolic link will not be followed.
140  Bool isRegular (Bool followSymLink = True) const;
141 
142  // Check if the file is a directory. If the boolean followSymLink is
143  // False a symbolic link will not be followed.
144  Bool isDirectory (Bool followSymLink = True) const;
145 
146  // Check if the file is a symbolic link.
147  Bool isSymLink() const;
148 
149  // Check if the file is a pipe.
150  Bool isPipe() const;
151 
152  // Check if the file is a character special file.
154 
155  // Check if the file is a block special file.
157 
158  // Check if the file is a socket.
159  Bool isSocket() const;
160 
161  // Check if the file exists.
162  Bool exists() const;
163 
164  // Check if the file is readable.
165  Bool isReadable() const;
166 
167  // Check if the file is writable.
168  Bool isWritable() const;
169 
170  // Check if the file is executable.
172 
173  // Check if a file can be created.
174  Bool canCreate() const;
175 
176  // Return the userID of the file.
177  long userID() const;
178 
179  // Return the groupID of the file.
180  long groupID() const;
181 
182  // Return the size of the file. If the file
183  // does not exist, an exception will be thrown.
184  virtual Int64 size() const;
185 
186  // Return the permissions as a decimal value.
188 
189  // Set permission with perm. Perm is an octal value.
190  void setPermissions (uInt permissions);
191 
192  // Update access time and modification time of a file.
193  void touch (uInt time);
194 
195  // Update access time and modification time of a file. This function
196  // updates the file with the current time.
197  void touch();
198 
199  // Time related fucnctions:
200  // Return the time when the file was last accessed in seconds since
201  // 00:00:00 GMT Jan 1, 1970.
202  uInt accessTime() const;
203 
204  // Return the time when the file was last accessed
205  // as a 26-characters String of the form:
206  // Thu Feb 3 13:40:11 1994
208 
209  // Return the time when the file was last modified in seconds since
210  // 00:00:00 GMT Jan 1, 1970.
211  uInt modifyTime() const;
212 
213  // Return the time when the file was last modified
214  // as a 26-characters String of the form:
215  // Thu Feb 3 13:40:11 1994
217 
218  // Return the time when the file status was last changed in seconds since
219  // 00:00:00 GMT Jan 1, 1970.
220  // It is set both by writing and changing the file status information,
221  // such as changes of owner, group, link count, or mode.
223 
224  // return the time when the file status was last changed
225  // as a 26-characters String of the form:
226  // Thu Feb 3 13:40:11 1994
228 
229  // Create a new unique path name in the specified directory, with
230  // the specified prefix and random trailing characters:
231  // <srcblock>
232  // p.newUniqueName ("./", "temp") --> "./tempAAA00xx32"
233  // p.newUniqueName ("/home/me", "diary") --> "/home/me/diaryAAA00xxb0"
234  // </srcblock>
235  static Path newUniqueName (const String& directory, const String& prefix);
236 
237  // Create a new unique filename without a prefix.
238  // As above, but all the characters in the filename are random:
239  // <srcblock>
240  // p.newUniqueName ("./") --> "./AAA00xx32"
241  // p.newUniqueName ("/home/me") --> "/home/me/AAA00xxb0"
242  // </srcblock>
243  static Path newUniqueName (const String& directory);
244 
245 
246  // get write status of the file.
247  // OVERWRITABLE - file exists and can be overwritten
248  // NOT_OVERWRITABLE - file exists but cannot be overwritten
249  // CREATABLE - File does not exist and can be created
250  // NOT_CREATABLE - file does not exist and cannot be created.
252 
253  // Return the filesystem type.
254  // If the file doesn't exsist crawl up the directory tree to
255  // find one that does.
256  String getFSType() const;
257 
258 protected:
259  // This function is used by <linkto class=RegularFile>RegularFile</linkto>
260  // and <linkto class=Directory>Directory</linkto> to remove all the links
261  // which, when followed, ultimately resolve to a Directory or a
262  // RegularFile.
263  // For example, A->B, B->C, C->D and D points to a regular file.
264  // When remove() is called for a regular file A,
265  // that function uses removeLinks() to remove A, B, C and D.
267 
268  // Check if the new path for a copy or move is valid.
269  // An exception is thrown if:
270  // <br>- the target directory is not writable
271  // <br>- or the target file already exists and overwrite==False
272  // <br>- or the target file already exists and is not writable
273  // <br>When the targetName represents a directory, the basename
274  // of the file is appended to it. This is done to cover the
275  // case where the source is a symlink to a file. In that case
276  // the target will get the basename of the symlink and not the
277  // the basename of the file pointed to. This is not done when
278  // forDirectory==True (which is used by class Directory).
279  void checkTarget (Path& targetName, Bool overwrite,
280  Bool forDirectory = False) const;
281 
282 private:
283  // Define a function for lstat.
284  // This is necessary since SunOS4.1.x prototypes lstat() with a first
285  // argument of type (char*), while Solaris (and presumably all other
286  // reasonable OS's) prototype it with a first argument of type
287  // (const char*). Since lstat() does not change its first argument,
288  // it is safe to convert our const variable to a non-const one so that
289  // we can call lstat() successfully.
290  // <br>It is also useful to be able to pass the buffer as void*. In that
291  // way the 32-bit or 64-bit file details are only needed in the cc file.
292  int mylstat (const char* path, void* buf) const;
293 
294  // Get the lstat of this file.
295  // Throw an exception when it fails.
296  void getstat (void* buf) const;
297 
298  // Get the lstat of a file.
299  // Throw an exception when it fails.
300  void getstat (const File& file, void* buf) const;
301 
302 
303  // Full pathname of the file.
305  // A sequence number to generate unique file names.
306  static std::atomic<uInt> uniqueSeqnr_p;
307 };
308 
309 
310 inline const Path& File::path() const
311 {
312  return itsPath;
313 }
314 
315 inline void File::getstat (void* buf) const
316 {
317  getstat (*this, buf);
318 }
319 
320 
321 
322 //# The ifdef's below are similar to those in IO/LargeIOFuncDef.h.
323 #if !defined(AIPS_NOLARGEFILE)
324 # ifdef AIPS_LINUX
325 # if !defined(_LARGEFILE64_SOURCE)
326 # define _LARGEFILE64_SOURCE
327 # endif
328 # endif
329 #if defined(AIPS_DARWIN) || defined(AIPS_BSD)
330 # define fileFSTAT fstat
331 # define fileLSTAT lstat
332 # define fileSTAT stat
333 # define fileSTATFS statfs
334 #else
335 # define fileFSTAT fstat64
336 # define fileLSTAT lstat64
337 # define fileSTAT stat64
338 # define fileSTATFS statfs64
339 #endif
340 #else
341 # define fileFSTAT fstat
342 # define fileLSTAT lstat
343 # define fileSTAT stat
344 # define fileSTATFS statfs
345 #endif
346 
347 
348 
349 } //# NAMESPACE CASACORE - END
350 
351 #endif
casacore::File::isSocket
Bool isSocket() const
Check if the file is a socket.
casacore::File::modifyTimeString
String modifyTimeString() const
Return the time when the file was last modified as a 26-characters String of the form: Thu Feb 3 13:4...
casacore::File::accessTime
uInt accessTime() const
Time related fucnctions: Return the time when the file was last accessed in seconds since 00:00:00 GM...
casacore::File::canCreate
Bool canCreate() const
Check if a file can be created.
casacore::File::File
File(const String &path)
casacore::File::exists
Bool exists() const
Check if the file exists.
casacore::File::NOT_OVERWRITABLE
@ NOT_OVERWRITABLE
file exists but cannot be overwritten
Definition: File.h:109
casacore::File::readPermissions
uInt readPermissions() const
Return the permissions as a decimal value.
casacore::File::newUniqueName
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 traili...
casacore::File::removeSymLinks
void removeSymLinks()
This function is used by RegularFile and Directory to remove all the links which,...
casacore::File::statusChangeTimeString
String statusChangeTimeString() const
return the time when the file status was last changed as a 26-characters String of the form: Thu Feb ...
casacore::File::NOT_CREATABLE
@ NOT_CREATABLE
file does not exist but cannot be created
Definition: File.h:113
casacore::File::newUniqueName
static Path newUniqueName(const String &directory)
Create a new unique filename without a prefix.
casacore::File::modifyTime
uInt modifyTime() const
Return the time when the file was last modified in seconds since 00:00:00 GMT Jan 1,...
casacore::File::operator=
File & operator=(const File &that)
Assignment (copy semantics).
casacore::File::isBlockSpecial
Bool isBlockSpecial() const
Check if the file is a block special file.
casacore::File::path
const Path & path() const
Returns the pathname of the file.
Definition: File.h:310
casacore::File::uniqueSeqnr_p
static std::atomic< uInt > uniqueSeqnr_p
A sequence number to generate unique file names.
Definition: File.h:306
casacore::File::getstat
void getstat(void *buf) const
Get the lstat of this file.
Definition: File.h:315
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::File::checkTarget
void checkTarget(Path &targetName, Bool overwrite, Bool forDirectory=False) const
Check if the new path for a copy or move is valid.
casacore::File::itsPath
Path itsPath
Full pathname of the file.
Definition: File.h:304
casacore::File::File
File()
Construct a File object whose Path is set to the current working directory.
casacore::File::isPipe
Bool isPipe() const
Check if the file is a pipe.
casacore::File::userID
long userID() const
Return the userID of the file.
casacore::File::setPermissions
void setPermissions(uInt permissions)
Set permission with perm.
casacore::File::mylstat
int mylstat(const char *path, void *buf) const
Define a function for lstat.
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::File::isSymLink
Bool isSymLink() const
Check if the file is a symbolic link.
casacore::File::OVERWRITABLE
@ OVERWRITABLE
file exists and can be overwritten
Definition: File.h:107
casacore::True
const Bool True
Definition: aipstype.h:43
casacore::File::isDirectory
Bool isDirectory(Bool followSymLink=True) const
Check if the file is a directory.
casacore::time
TableExprNode time(const TableExprNode &node)
Definition: ExprNode.h:1537
casacore::File::getFSType
String getFSType() const
Return the filesystem type.
casacore::File::isReadable
Bool isReadable() const
Check if the file is readable.
casacore::File::accessTimeString
String accessTimeString() const
Return the time when the file was last accessed as a 26-characters String of the form: Thu Feb 3 13:4...
casacore::File::File
File(const File &that)
Copy constructor (copy semantics).
casacore::File
Definition: File.h:102
casacore::File::isExecutable
Bool isExecutable() const
Check if the file is executable.
casacore::File::FileWriteStatus
FileWriteStatus
Definition: File.h:105
casacore::Int64
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
casacore::File::CREATABLE
@ CREATABLE
file does not exist and is creatable
Definition: File.h:111
casacore::File::size
virtual Int64 size() const
Return the size of the file.
casacore::File::isWritable
Bool isWritable() const
Check if the file is writable.
casacore::File::touch
void touch()
Update access time and modification time of a file.
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::Path
Definition: Path.h:127
casacore::File::groupID
long groupID() const
Return the groupID of the file.
casacore::File::getWriteStatus
FileWriteStatus getWriteStatus() const
get write status of the file.
casacore::File::isRegular
Bool isRegular(Bool followSymLink=True) const
Check if the file is a regular file.
casacore::File::touch
void touch(uInt time)
Update access time and modification time of a file.
casacore::File::~File
virtual ~File()
casacore::File::isCharacterSpecial
Bool isCharacterSpecial() const
Check if the file is a character special file.
casacore::File::getstat
void getstat(const File &file, void *buf) const
Get the lstat of a file.
casacore::File::File
File(const Path &path)
Construct a File object whose Path is set to the given Path.
casacore::File::statusChangeTime
uInt statusChangeTime() const
Return the time when the file status was last changed in seconds since 00:00:00 GMT Jan 1,...