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
String getFSType() const
Return the filesystem type.
File(const Path &path)
Construct a File object whose Path is set to the given Path.
Bool canCreate() const
Check if a file can be created.
File & operator=(const File &that)
Assignment (copy semantics).
Bool isPipe() const
Check if the file is a pipe.
uInt statusChangeTime() const
Return the time when the file status was last changed in seconds since 00:00:00 GMT Jan 1,...
File(const String &path)
void removeSymLinks()
This function is used by RegularFile and Directory to remove all the links which,...
void getstat(void *buf) const
Get the lstat of this file.
Definition: File.h:315
uInt accessTime() const
Time related fucnctions: Return the time when the file was last accessed in seconds since 00:00:00 GM...
Bool isBlockSpecial() const
Check if the file is a block special file.
FileWriteStatus getWriteStatus() const
get write status of the file.
Bool isWritable() const
Check if the file is writable.
uInt readPermissions() const
Return the permissions as a decimal value.
Bool isSocket() const
Check if the file is a socket.
Bool isSymLink() const
Check if the file is a symbolic link.
void checkTarget(Path &targetName, Bool overwrite, Bool forDirectory=False) const
Check if the new path for a copy or move is valid.
virtual Int64 size() const
Return the size of the file.
uInt modifyTime() const
Return the time when the file was last modified in seconds since 00:00:00 GMT Jan 1,...
void setPermissions(uInt permissions)
Set permission with perm.
void touch(uInt time)
Update access time and modification time of a file.
Bool isReadable() const
Check if the file is readable.
void touch()
Update access time and modification time of a file.
File(const File &that)
Copy constructor (copy semantics).
Bool isCharacterSpecial() const
Check if the file is a character special 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...
static std::atomic< uInt > uniqueSeqnr_p
A sequence number to generate unique file names.
Definition: File.h:306
virtual ~File()
long groupID() const
Return the groupID of the file.
void getstat(const File &file, void *buf) const
Get the lstat of a file.
String statusChangeTimeString() const
return the time when the file status was last changed as a 26-characters String of the form: Thu Feb ...
Bool isDirectory(Bool followSymLink=True) const
Check if the file is a directory.
@ NOT_OVERWRITABLE
file exists but cannot be overwritten
Definition: File.h:109
@ OVERWRITABLE
file exists and can be overwritten
Definition: File.h:107
@ NOT_CREATABLE
file does not exist but cannot be created
Definition: File.h:113
@ CREATABLE
file does not exist and is creatable
Definition: File.h:111
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:310
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...
Bool exists() const
Check if the file exists.
long userID() const
Return the userID of the file.
Bool isRegular(Bool followSymLink=True) const
Check if the file is a regular file.
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...
Bool isExecutable() const
Check if the file is executable.
Path itsPath
Full pathname of the file.
Definition: File.h:304
static Path newUniqueName(const String &directory)
Create a new unique filename without a prefix.
File()
Construct a File object whose Path is set to the current working directory.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
TableExprNode time(const TableExprNode &node)
Definition: ExprNode.h:1580
unsigned int uInt
Definition: aipstype.h:51
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43