casacore
Directory.h
Go to the documentation of this file.
1 //# Directory.h: Get information about, and manipulate directories
2 //# Copyright (C) 1996,1997,1999
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_DIRECTORY_H
29 #define CASA_DIRECTORY_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Arrays/ArrayFwd.h>
34 #include <casacore/casa/OS/Path.h>
35 #include <casacore/casa/OS/File.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 class Regex;
40 class String;
41 
42 // <summary>
43 // Get information about, and manipulate directories
44 // </summary>
45 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
46 // </reviewed>
47 
48 // <use visibility=export>
49 
50 // <prerequisite>
51 // <li> Basic knowledge of the UNIX file system
52 // <li> <linkto class=File>File</linkto>
53 // </prerequisite>
54 
55 // <synopsis>
56 // Directory provides functions to manipulate and to get information about
57 // directories. The functions for getting information (like ownership, dates)
58 // about directories are inherited from the <linkto class=File>File</linkto>
59 // class.
60 // Directory itself provides functions to create, copy, move, or remove
61 // a directory. The file name can be a symbolic link resolving
62 // (eventually) to a directory.
63 // <p>
64 // A separate class <linkto class=DirectoryIterator>DirectoryIterator</linkto>
65 // allows one to traverse a directory to get the file names in it.
66 // </synopsis>
67 
68 // <example>
69 // <srcblock>
70 // Directory dir("someDir");
71 // // Create directory someDir in the working directory.
72 // dir.create();
73 // cout << dir.nEntries(); // #entries
74 // // Assign to another directory.
75 // dir = Directory("otherDir");
76 // // Remove the directory and its contents.
77 // dir.removeRecursive();
78 // </srcblock>
79 // </example>
80 
81 // <motivation>
82 // Provide functions for manipulating and getting information
83 // about directories.
84 // </motivation>
85 
86 
87 class Directory: public File
88 {
89 public:
90 
91  // Sets the path on the current working directory
93 
94  // Create a directory object for a file with the given path name.
95  // An exception is thrown if the directory is illegal, i.e. if it does
96  // not exist as a directory or symbolic link or if cannot be created.
97  // Note that the directory is not created if it does not exist yet.
98  // This can be done using the function create.
99  // <br>
100  // When the given path name is a symbolic link, the symbolic link
101  // is resolved (recursively) and the resulting directory name is used
102  // instead.
103  // <group>
104  Directory (const Path& name);
105  Directory (const String& name);
106  Directory (const File& name);
107  // </group>
108 
109  // Copy constructor (copy semantics).
110  Directory (const Directory& that);
111 
113 
114  // Assignment (copy semantics).
116 
117  // Check if directory is empty.
118  // If the directory does not exist, an exception will be thrown.
119  Bool isEmpty() const;
120 
121  // Return the number of entries in the directory (not counting . and ..).
122  // If the directory does not exist, an exception will be thrown.
123  uInt nEntries() const;
124 
125  // Get the amount of free space (in bytes) on the file system this
126  // directory is on. When the directory path is a symbolic link, that
127  // link is resolved first.
128  // <group>
129  Double freeSpace() const;
130  uInt freeSpaceInMB() const;
131  // </group>
132 
133  // Create the directory.
134  // <br>If the directory exists and overwrite=True, it will be removed
135  // (recursively). Otherwise an exception is thrown.
136  void create (Bool overwrite = True);
137 
138  // Remove a directory.
139  // An exception is thrown if the directory is not empty.
140  // If a symbolic link is given, the link chain pointing to the directory
141  // will also be removed.
142  void remove();
143 
144  // Remove all files in the directory except subdirectories.
145  // The directory itself is not removed.
146  void removeFiles();
147 
148  // Remove the directory and its contents (recursively in all
149  // subdirectories).
150  // If <src>keepDir==True</src>, the directory itself is kept
151  //(to keep properties like placement on Lustre).
152  void removeRecursive (Bool keepDir = False);
153 
154  // Copy the directory and its contents (recursively) to the target
155  // path using the system command cp -r.
156  // If the target already exists (as a file, directory or symlink),
157  // and overwrite=True, it will first be removed.
158  // The target directory is created and the data in the source
159  // directory is copied to the new directory.
160  // <br>An exception is thrown if:
161  // <br>- the target directory is not writable
162  // <br>- or the target already exists and overwrite!=True
163  // <note role=caution>
164  // 1. The behavior of this copy function is different from cp when the
165  // target directory already exists. Cp copies the source to a
166  // subdirectory of the target, while copy recreates the target.
167  // <br>2. When a readonly file is copied, <src>cp</src> the resulting
168  // file is also readonly. Therefore <src>chmod</src> is used to
169  // set user write permission after the copy.
170  // The flag <src>setUserWritePermission</src> can be set to False
171  // when that should not be done.
172  // </note>
173  // <group>
174  void copy (const Path& target, Bool overwrite = True,
175  Bool setUserWritePermission = True) const;
176  void copy (const String& target, Bool overwrite = True,
177  Bool setUserWritePermission = True) const;
178  // </group>
179 
180  // Copy a directory recursively in a manual way.
181  // This is used in a copy using the system command is not possible
182  // (like on the Cray XT3).
183  void copyRecursive (const String& target) const;
184 
185  // Move the directory to the target path using the system command mv.
186  // If the target already exists (as a file, directory or symlink),
187  // and overwrite=True, it will first be removed.
188  // The source directory is moved (thus renamed) to the target.
189  // <br>An exception is thrown if:
190  // <br>- the target directory is not writable
191  // <br>- or the target already exists and overwrite!=True
192  // <note role=caution>
193  // The behavior of this move function is different from mv when the
194  // target directory already exists. Mv moves the source to a
195  // subdirectory of the target, while move recreates the target.
196  // </note>
197  // <group>
198  void move (const Path& target, Bool overwrite = True);
199  void move (const String& target, Bool overwrite = True);
200  // </group>
201 
202  // Find all files which whose names match <src>regex</src>. You
203  // can do this recursively (default) or not. Note that the
204  // matching is a regular expression match, not a shell file-expansion
205  // match. However, a shell file pattern can be converted to a regexp
206  // using the function <linkto class=Regex>Regex::fromPattern</linkto>.
207  // <src>Regex::fromString</src> allows one to convert a file name
208  // to a regexp and to use this function for eact file name matching.
209  // <br>To match the semantics of the unix <src>find</src> command,
210  // symbolic links are not followed by default, but this behavior
211  // can be over-ridden.
212  Vector<String> find (const Regex& regexp, Bool followSymLinks=False,
213  Bool recursive=True) const;
214 
215 
216  // For each element of <src>files</src>, find all file names matching
217  // it using shell file-expansion rules. Return the list of all matched files
218  // as absolute path + file names. You may optionally drop the path and just return
219  // the file names. Note tha if <src>files(i)</src> contains a path as well as a file
220  // name, no matching is done on the path, just the trailing file name.
221  // Throws an AipsError if the shell pattern is illegal.
222  static Vector<String> shellExpand (const Vector<String>& files, Bool stripPath=False);
223  // Return the total size of everything in the Directory. If the Directory
224  // does not exist, an exception will be thrown.
225  virtual Int64 size() const;
226 
227  //Check if a directory is mounted via NFS or not.
229 
230 private:
231  // Check if the path defines a directory.
232  // Also resolve possible symlinks.
233  void checkPath();
234 
235  // This variable is used when a symbolic link is given to be
236  // a directory.
238 };
239 
240 
241 
242 inline void Directory::copy (const String& target, Bool overwrite,
243  Bool setUserWritePermission) const
244 {
245  copy (Path(target), overwrite, setUserWritePermission);
246 }
247 inline void Directory::move (const String& target, Bool overwrite)
248 {
249  move (Path(target), overwrite);
250 }
252 {
253  return uInt (0.5 + freeSpace() / (1024*1024));
254 }
255 
256 
257 
258 } //# NAMESPACE CASACORE - END
259 
260 #endif
void remove()
Remove a directory.
virtual Int64 size() const
Return the total size of everything in the Directory.
Directory(const Path &name)
Create a directory object for a file with the given path name.
Bool isNFSMounted() const
Check if a directory is mounted via NFS or not.
Double freeSpace() const
Get the amount of free space (in bytes) on the file system this directory is on.
static Vector< String > shellExpand(const Vector< String > &files, Bool stripPath=False)
For each element of files, find all file names matching it using shell file-expansion rules.
Directory(const String &name)
void copy(const Path &target, Bool overwrite=True, Bool setUserWritePermission=True) const
Copy the directory and its contents (recursively) to the target path using the system command cp -r.
void move(const Path &target, Bool overwrite=True)
Move the directory to the target path using the system command mv.
void removeFiles()
Remove all files in the directory except subdirectories.
Directory(const File &name)
void create(Bool overwrite=True)
Create the directory.
void checkPath()
Check if the path defines a directory.
Directory & operator=(const Directory &that)
Assignment (copy semantics).
Directory()
Sets the path on the current working directory.
uInt freeSpaceInMB() const
Definition: Directory.h:251
File itsFile
This variable is used when a symbolic link is given to be a directory.
Definition: Directory.h:237
void copyRecursive(const String &target) const
Copy a directory recursively in a manual way.
void removeRecursive(Bool keepDir=False)
Remove the directory and its contents (recursively in all subdirectories).
Bool isEmpty() const
Check if directory is empty.
Directory(const Directory &that)
Copy constructor (copy semantics).
uInt nEntries() const
Return the number of entries in the directory (not counting.
Vector< String > find(const Regex &regexp, Bool followSymLinks=False, Bool recursive=True) const
Find all files which whose names match regex.
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
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
double Double
Definition: aipstype.h:55