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