fileOperation.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration | Website: https://openfoam.org
5  \\ / A nd | Copyright (C) 2017-2021 OpenFOAM Foundation
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8 License
9  This file is part of OpenFOAM.
10 
11  OpenFOAM is free software: you can redistribute it and/or modify it
12  under the terms of the GNU General Public License as published by
13  the Free Software Foundation, either version 3 of the License, or
14  (at your option) any later version.
15 
16  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
17  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
18  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
19  for more details.
20 
21  You should have received a copy of the GNU General Public License
22  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
23 
24 Class
25  Foam::fileOperation
26 
27 \*---------------------------------------------------------------------------*/
28 
29 #ifndef fileOperation_H
30 #define fileOperation_H
31 
32 #include "ISstream.H"
33 #include "Ostream.H"
34 #include "autoPtr.H"
35 #include "fileNameList.H"
36 #include "instantList.H"
37 #include "fileMonitor.H"
38 #include "labelList.H"
39 #include "Switch.H"
40 #include "tmpNrc.H"
41 #include "NamedEnum.H"
42 
43 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
44 
45 namespace Foam
46 {
47 
48 class IOobject;
49 class regIOobject;
50 class objectRegistry;
51 class Time;
52 
53 /*---------------------------------------------------------------------------*\
54  Class fileOperation Declaration
55 \*---------------------------------------------------------------------------*/
56 
57 class fileOperation
58 {
59 public:
60 
61  //- Enumeration for the location of an IOobject
62  enum pathType
63  {
64  NOTFOUND, // not found
65  ABSOLUTE, // instance is absolute directory
66  OBJECT, // io.objectPath() exists
67  WRITEOBJECT, // write path exists
68  PROCUNCOLLATED, // objectPath exists in processor0
69  PROCBASEOBJECT, // objectPath exists in specified, constant
70  // processorsDir (usually 'processorsDDD')
71  PROCOBJECT, // objectPath exists in locally differing
72  // processorsDir (e.g. 'processorsDDD_0-1')
73  PARENTOBJECT, // parent of object path
74  FINDINSTANCE, // file found in time directory
75  PROCUNCOLLATEDINSTANCE, // as PROCUNCOLLATED but with instance
76  PROCBASEINSTANCE, // as PROCBASEOBJECT but with instance
77  PROCINSTANCE // as PROCOBJECT but with instance
78  };
79 
81 
82  //- Description of processor directory naming:
83  // - processor directory naming
84  // - whether directory contains a range
85  // (so differs on different processors)
86  // - index in range
88 
90 
91 
92 protected:
93 
94  // Protected data
95 
96  //- Communicator to use
97  const label comm_;
98 
99  //- Detected processors directories
101 
102  //- file-change monitor for all registered files
104 
105 
106  // Protected Member Functions
107 
108  fileMonitor& monitor() const;
109 
110  //- Sort directory entries according to time value
111  static instantList sortTimes(const fileNameList&, const word&);
112 
113  //- Merge two times
114  static void mergeTimes
115  (
116  const instantList& extraTimes,
117  const word& constantName,
118  instantList& times
119  );
120 
121  //- Helper: check for file (isFile) or directory (!isFile)
122  static bool isFileOrDir(const bool isFile, const fileName&);
123 
124  //- Detect presence of processorsDDD
125  void cacheProcessorsPath(const fileName& fName) const;
126 
127  //- Lookup name of processorsDDD using cache. Return empty fileName
128  // if not found
130 
131  //- Does ioobject exist. Is either a directory (empty name()) or
132  // a file
133  bool exists(IOobject& io) const;
134 
135 
136 public:
137 
138  // Static data
139 
140  //- Return the processors directory name (usually "processors")
141  static word processorsBaseDir;
142 
143  //- Default fileHandler
144  static word defaultFileHandler;
145 
146 
147  // Public data types
148 
149  //- Runtime type information
150  TypeName("fileOperation");
151 
152 
153  //- Static fileOperation
155 
156 
157  // Constructors
158 
159  //- Construct null
160  fileOperation(const label comm);
161 
162 
163  // Declare run-time constructor selection table
164 
166  (
167  autoPtr,
169  word,
170  (
171  const bool verbose
172  ),
173  (verbose)
174  );
175 
176 
177  // Selectors
178 
179  //- Select type
180  static autoPtr<fileOperation> New(const word& type, const bool verbose);
181 
182 
183  //- Destructor
184  virtual ~fileOperation();
185 
186 
187  // Member Functions
188 
189  // OSSpecific equivalents
190 
191  //- Make directory
192  virtual bool mkDir(const fileName&, mode_t=0777) const = 0;
193 
194  //- Set the file mode
195  virtual bool chMod(const fileName&, const mode_t) const = 0;
196 
197  //- Return the file mode
198  virtual mode_t mode
199  (
200  const fileName&,
201  const bool checkVariants = true,
202  const bool followLink = true
203  ) const = 0;
204 
205  //- Return the file type: directory, file or link
206  virtual fileType type
207  (
208  const fileName&,
209  const bool checkVariants = true,
210  const bool followLink = true
211  ) const = 0;
212 
213  //- Does the name exist (as directory or file) in the file system?
214  // Optionally enable/disable check for gzip file.
215  virtual bool exists
216  (
217  const fileName&,
218  const bool checkVariants = true,
219  const bool followLink = true
220  ) const = 0;
221 
222  //- Does the name exist as a directory in the file system?
223  virtual bool isDir
224  (
225  const fileName&,
226  const bool followLink = true
227  ) const = 0;
228 
229  //- Does the name exist as a file in the file system?
230  // Optionally enable/disable check for gzip file.
231  virtual bool isFile
232  (
233  const fileName&,
234  const bool checkVariants = true,
235  const bool followLink = true
236  ) const = 0;
237 
238  //- Return size of file
239  virtual off_t fileSize
240  (
241  const fileName&,
242  const bool checkVariants = true,
243  const bool followLink = true
244  ) const = 0;
245 
246  //- Return time of last file modification
247  virtual time_t lastModified
248  (
249  const fileName&,
250  const bool checkVariants = true,
251  const bool followLink = true
252  ) const = 0;
253 
254  //- Return time of last file modification
255  virtual double highResLastModified
256  (
257  const fileName&,
258  const bool checkVariants = true,
259  const bool followLink = true
260  ) const = 0;
261 
262  //- Read a directory and return the entries as a string list
263  virtual fileNameList readDir
264  (
265  const fileName&,
266  const fileType = fileType::file,
267  const bool filterVariants = true,
268  const bool followLink = true
269  ) const = 0;
270 
271  //- Copy, recursively if necessary, the source to the destination
272  virtual bool cp
273  (
274  const fileName& src,
275  const fileName& dst,
276  const bool followLink = true
277  ) const = 0;
278 
279  //- Create a softlink. dst should not exist. Returns true if
280  // successful.
281  virtual bool ln(const fileName& src, const fileName& dst) const = 0;
282 
283  //- Rename src to dst
284  virtual bool mv
285  (
286  const fileName& src,
287  const fileName& dst,
288  const bool followLink = false
289  ) const = 0;
290 
291  //- Rename to a corresponding backup file
292  // If the backup file already exists, attempt with
293  // "01" .. "99" suffix
294  virtual bool mvBak
295  (
296  const fileName&,
297  const std::string& ext = "bak"
298  ) const = 0;
299 
300  //- Remove a file, returning true if successful otherwise false
301  virtual bool rm(const fileName&) const = 0;
302 
303  //- Remove a directory and its contents
304  virtual bool rmDir(const fileName&) const = 0;
305 
306  // //- Open a shared library. Return handle to library. Print error
307  // // message if library cannot be loaded (check = true)
308  // virtual void* dlOpen
309  // (
310  // const fileName& lib,
311  // const bool check = true
312  // ) const = 0;
313 
314 
315  // (reg)IOobject functionality
316 
317  //- Generate disk file name for object. Opposite of filePath.
318  // Optional wanted typeName.
319  virtual fileName objectPath
320  (
321  const IOobject& io,
322  const word& typeName
323  ) const;
324 
325  //- Search for an object. globalFile : also check undecomposed case
326  // Optional wanted typeName.
327  virtual fileName filePath
328  (
329  const bool globalFile,
330  const IOobject&,
331  const word& typeName
332  ) const = 0;
333 
334  //- Search for a directory. globalFile : also check undecomposed
335  // case
336  virtual fileName dirPath
337  (
338  const bool globalFile,
339  const IOobject&
340  ) const = 0;
341 
342  //- Search directory for objects. Used in IOobjectList.
343  virtual fileNameList readObjects
344  (
345  const objectRegistry& db,
346  const fileName& instance,
347  const fileName& local,
348  word& newInstance
349  ) const;
350 
351  //- Read object header from supplied file
352  virtual bool readHeader
353  (
354  IOobject&,
355  const fileName&,
356  const word& typeName
357  ) const = 0;
358 
359  //- Reads header for regIOobject and returns an ISstream
360  // to read the contents.
362  (
363  regIOobject&,
364  const fileName&,
365  const word& typeName,
366  const bool read = true
367  ) const = 0;
368 
369  //- Top-level read
370  // Format set to ASCII if defaultFormat and file format are ASCII
371  virtual bool read
372  (
373  regIOobject&,
374  const bool masterOnly,
375  const IOstream::streamFormat defaultFormat,
376  const word& typeName
377  ) const = 0;
378 
379  //- Writes a regIOobject (so header, contents and divider).
380  // Returns success state. Default action is to write to
381  // the objectPath using writeData. If !write the
382  // file does not need to be written (this is used e.g. to
383  // suppress empty local lagrangian data)
384  virtual bool writeObject
385  (
386  const regIOobject&,
390  const bool write = true
391  ) const;
392 
393 
394  // Filename (not IOobject) operations
395 
396  //- Search for a file or directory. Use IOobject version in
397  // preference
398  virtual fileName filePath(const fileName&) const;
399 
400  //- Generate an ISstream that reads a file
402  (
403  const fileName& filePath,
406  ) const = 0;
407 
408  //- Generate an Ostream that writes a file
410  (
411  const fileName& filePath,
415  const bool write = true
416  ) const = 0;
417 
418 
419  // File modification checking
420 
421  //- Add watching of a file. Returns handle
422  virtual label addWatch(const fileName&) const;
423 
424  //- Remove watch on a file (using handle)
425  virtual bool removeWatch(const label) const;
426 
427  //- Find index (or -1) of file in list of handles
428  virtual label findWatch
429  (
430  const labelList& watchIndices,
431  const fileName&
432  ) const;
433 
434  //- Helper: add watches for list of regIOobjects
435  virtual void addWatches(regIOobject&, const fileNameList&) const;
436 
437  //- Get name of file being watched (using handle)
438  virtual fileName getFile(const label) const;
439 
440  //- Update state of all files
441  virtual void updateStates
442  (
443  const bool masterOnly,
444  const bool syncPar
445  ) const;
446 
447  //- Get current state of file (using handle)
448  virtual fileMonitor::fileState getState(const label) const;
449 
450  //- Set current state of file (using handle) to unmodified
451  virtual void setUnmodified(const label) const;
452 
453 
454  // Other
455 
456  //- Actual name of processors dir (for use in mode PROCOBJECT,
457  // PROCINSTANCE)
458  virtual word processorsDir(const IOobject& io) const
459  {
460  return processorsBaseDir;
461  }
462 
463  //- Actual name of processors dir (for use in mode PROCOBJECT,
464  // PROCINSTANCE)
465  virtual word processorsDir(const fileName&) const
466  {
467  return processorsBaseDir;
468  }
469 
470  //- Set number of processor directories/results. Only used in
471  // decomposePar
472  virtual void setNProcs(const label nProcs);
473 
474  //- Get number of processor directories/results. Used for e.g.
475  // reconstructPar, argList checking
476  virtual label nProcs
477  (
478  const fileName& dir,
479  const fileName& local = ""
480  ) const;
481 
482  //- Get sorted list of times
483  virtual instantList findTimes(const fileName&, const word&) const;
484 
485  //- Find instance where IOobject is. Fails if cannot be found
486  // and readOpt() is MUST_READ/MUST_READ_IF_MODIFIED. Otherwise
487  // returns stopInstance.
488  virtual IOobject findInstance
489  (
490  const IOobject& io,
491  const scalar startValue,
492  const word& stopInstance
493  ) const;
494 
495  //- Callback for time change
496  virtual void setTime(const Time&) const
497  {}
498 
499  //- Forcibly wait until all output done. Flush any cached data
500  virtual void flush() const;
501 
502  //- Generate path (like io.path) from root+casename with any
503  // 'processorXXX' replaced by procDir (usually 'processors')
505  (
506  const IOobject&,
507  const word& procDir
508  ) const;
509 
510  //- Generate path (like io.path) with provided instance and any
511  // 'processorXXX' replaced by procDir (usually 'processors')
513  (
514  const IOobject&,
515  const word& instance,
516  const word& procDir
517  ) const;
518 
519  //- Operating on fileName: replace processorXXX with procDir
520  fileName processorsPath(const fileName&, const word& procDir) const;
521 
522  //- Split fileName into part before 'processor' and part after.
523  // Returns -1 or processor number and optionally number
524  // of processors. Use with care.
525  // - path/"processor"+Foam::name(proci)/local reconstructs input
526  // - path/"processors"+Foam::name(nProcs)/local reconstructs
527  // collated processors equivalence
529  (
530  const fileName&,
531  fileName& path,
532  fileName& procDir,
533  fileName& local,
534  label& groupStart,
535  label& groupSize,
536  label& nProcs
537  );
538 
539  //- Detect processor number from '/aa/bb/processorDDD/cc'
540  static label detectProcessorPath(const fileName&);
541 };
542 
543 
544 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
545 // Global declarations: defined in fileOperation.C
546 
547 //- Get current file handler
548 const fileOperation& fileHandler();
549 
550 //- Reset file handler
552 
553 //- Recursively search the given directory for the file
554 // returning the path relative to the directory or
555 // fileName::null if not found
556 fileName search(const word& file, const fileName& directory);
557 
558 //- Copy all the files from the source to the target directory
559 void cpFiles(const fileName& srcDir, const fileName& targetDir);
560 
561 
562 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
563 
564 } // End namespace Foam
565 
566 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
567 
568 #endif
569 
570 // ************************************************************************* //
pathType
Enumeration for the location of an IOobject.
Definition: fileOperation.H:61
virtual bool rm(const fileName &) const =0
Remove a file, returning true if successful otherwise false.
autoPtr< fileMonitor > monitorPtr_
file-change monitor for all registered files
virtual bool rmDir(const fileName &) const =0
Remove a directory and its contents.
List< dirIndex > dirIndexList
Definition: fileOperation.H:88
A class for handling file names.
Definition: fileName.H:79
virtual off_t fileSize(const fileName &, const bool checkVariants=true, const bool followLink=true) const =0
Return size of file.
virtual fileMonitor::fileState getState(const label) const
Get current state of file (using handle)
virtual bool read(regIOobject &, const bool masterOnly, const IOstream::streamFormat defaultFormat, const word &typeName) const =0
Top-level read.
virtual bool chMod(const fileName &, const mode_t) const =0
Set the file mode.
Checking for changes to files.
Definition: fileMonitor.H:61
A 2-tuple for storing two objects of different types.
Definition: HashTable.H:65
A 1D array of objects of type <T>, where the size of the vector is known and used for subscript bound...
Definition: HashTable.H:59
void cpFiles(const fileName &srcDir, const fileName &targetDir)
Copy all the files from the source to the target directory.
virtual bool mvBak(const fileName &, const std::string &ext="bak") const =0
Rename to a corresponding backup file.
fileState
Enumeration defining the file state.
Definition: fileMonitor.H:69
virtual void setUnmodified(const label) const
Set current state of file (using handle) to unmodified.
virtual bool mkDir(const fileName &, mode_t=0777) const =0
Make directory.
bool exists(IOobject &io) const
Does ioobject exist. Is either a directory (empty name()) or.
virtual fileNameList readObjects(const objectRegistry &db, const fileName &instance, const fileName &local, word &newInstance) const
Search directory for objects. Used in IOobjectList.
virtual bool mv(const fileName &src, const fileName &dst, const bool followLink=false) const =0
Rename src to dst.
virtual ~fileOperation()
Destructor.
word format(conversionProperties.lookup("format"))
Tuple2< fileName, Tuple2< pathType, label > > dirIndex
Description of processor directory naming:
Definition: fileOperation.H:86
tmpNrc< dirIndexList > lookupProcessorsPath(const fileName &) const
Lookup name of processorsDDD using cache. Return empty fileName.
virtual autoPtr< ISstream > readStream(regIOobject &, const fileName &, const word &typeName, const bool read=true) const =0
Reads header for regIOobject and returns an ISstream.
fileName processorsPath(const IOobject &, const word &instance, const word &procDir) const
Generate path (like io.path) with provided instance and any.
Class to control time during OpenFOAM simulations that is also the top-level objectRegistry.
Definition: Time.H:69
declareRunTimeSelectionTable(autoPtr, fileOperation, word,(const bool verbose),(verbose))
virtual autoPtr< Ostream > NewOFstream(const fileName &filePath, IOstream::streamFormat format=IOstream::ASCII, IOstream::versionNumber version=IOstream::currentVersion, IOstream::compressionType compression=IOstream::UNCOMPRESSED, const bool write=true) const =0
Generate an Ostream that writes a file.
static autoPtr< fileOperation > New(const word &type, const bool verbose)
Select type.
void cacheProcessorsPath(const fileName &fName) const
Detect presence of processorsDDD.
virtual void updateStates(const bool masterOnly, const bool syncPar) const
Update state of all files.
virtual fileNameList readDir(const fileName &, const fileType=fileType::file, const bool filterVariants=true, const bool followLink=true) const =0
Read a directory and return the entries as a string list.
virtual bool ln(const fileName &src, const fileName &dst) const =0
Create a softlink. dst should not exist. Returns true if.
A class for handling words, derived from string.
Definition: word.H:59
virtual fileName getFile(const label) const
Get name of file being watched (using handle)
virtual fileName filePath(const bool globalFile, const IOobject &, const word &typeName) const =0
Search for an object. globalFile : also check undecomposed case.
virtual IOobject findInstance(const IOobject &io, const scalar startValue, const word &stopInstance) const
Find instance where IOobject is. Fails if cannot be found.
virtual instantList findTimes(const fileName &, const word &) const
Get sorted list of times.
streamFormat
Enumeration for the format of data in the stream.
Definition: IOstream.H:86
void write(std::ostream &os, const bool binary, List< floatScalar > &fField)
Write floats ascii or binary.
virtual void addWatches(regIOobject &, const fileNameList &) const
Helper: add watches for list of regIOobjects.
const fileOperation & fileHandler()
Get current file handler.
virtual label addWatch(const fileName &) const
Add watching of a file. Returns handle.
fileType
Enumeration of file types.
Definition: fileName.H:66
An STL-conforming hash table.
Definition: HashTable.H:61
virtual fileType type(const fileName &, const bool checkVariants=true, const bool followLink=true) const =0
Return the file type: directory, file or link.
virtual bool cp(const fileName &src, const fileName &dst, const bool followLink=true) const =0
Copy, recursively if necessary, the source to the destination.
static void mergeTimes(const instantList &extraTimes, const word &constantName, instantList &times)
Merge two times.
compressionType
Enumeration for the format of data in the stream.
Definition: IOstream.H:193
static word processorsBaseDir
Return the processors directory name (usually "processors")
virtual bool writeObject(const regIOobject &, IOstream::streamFormat format=IOstream::ASCII, IOstream::versionNumber version=IOstream::currentVersion, IOstream::compressionType compression=IOstream::UNCOMPRESSED, const bool write=true) const
Writes a regIOobject (so header, contents and divider).
fileName processorsCasePath(const IOobject &, const word &procDir) const
Generate path (like io.path) from root+casename with any.
fileOperation(const label comm)
Construct null.
fileMonitor & monitor() const
Definition: fileOperation.C:81
HashTable< dirIndexList > procsDirs_
Detected processors directories.
Definition: fileOperation.H:99
virtual time_t lastModified(const fileName &, const bool checkVariants=true, const bool followLink=true) const =0
Return time of last file modification.
virtual void flush() const
Forcibly wait until all output done. Flush any cached data.
A class for managing temporary objects without reference counting.
Definition: tmpNrc.H:52
static bool isFileOrDir(const bool isFile, const fileName &)
Helper: check for file (isFile) or directory (!isFile)
static autoPtr< fileOperation > fileHandlerPtr_
Static fileOperation.
virtual label nProcs(const fileName &dir, const fileName &local="") const
Get number of processor directories/results. Used for e.g.
virtual void setTime(const Time &) const
Callback for time change.
static word defaultFileHandler
Default fileHandler.
static const versionNumber currentVersion
Current version number.
Definition: IOstream.H:203
virtual bool isDir(const fileName &, const bool followLink=true) const =0
Does the name exist as a directory in the file system?
virtual fileName dirPath(const bool globalFile, const IOobject &) const =0
Search for a directory. globalFile : also check undecomposed.
static instantList sortTimes(const fileNameList &, const word &)
Sort directory entries according to time value.
Definition: fileOperation.C:99
virtual autoPtr< ISstream > NewIFstream(const fileName &filePath, IOstream::streamFormat format=IOstream::ASCII, IOstream::versionNumber version=IOstream::currentVersion) const =0
Generate an ISstream that reads a file.
Version number type.
Definition: IOstream.H:96
regIOobject is an abstract class derived from IOobject to handle automatic object registration with t...
Definition: regIOobject.H:52
const label comm_
Communicator to use.
Definition: fileOperation.H:96
fileName search(const word &file, const fileName &directory)
Recursively search the given directory for the file.
An auto-pointer similar to the STL auto_ptr but with automatic casting to a reference to the type and...
Definition: PtrList.H:52
static label detectProcessorPath(const fileName &)
Detect processor number from &#39;/aa/bb/processorDDD/cc&#39;.
TypeName("fileOperation")
Runtime type information.
Registry of regIOobjects.
virtual bool isFile(const fileName &, const bool checkVariants=true, const bool followLink=true) const =0
Does the name exist as a file in the file system?
virtual label findWatch(const labelList &watchIndices, const fileName &) const
Find index (or -1) of file in list of handles.
IOobject defines the attributes of an object for which implicit objectRegistry management is supporte...
Definition: IOobject.H:98
static const NamedEnum< pathType, 12 > pathTypeNames_
Definition: fileOperation.H:79
virtual fileName objectPath(const IOobject &io, const word &typeName) const
Generate disk file name for object. Opposite of filePath.
static label splitProcessorPath(const fileName &, fileName &path, fileName &procDir, fileName &local, label &groupStart, label &groupSize, label &nProcs)
Split fileName into part before &#39;processor&#39; and part after.
virtual void setNProcs(const label nProcs)
Set number of processor directories/results. Only used in.
virtual bool removeWatch(const label) const
Remove watch on a file (using handle)
virtual double highResLastModified(const fileName &, const bool checkVariants=true, const bool followLink=true) const =0
Return time of last file modification.
virtual bool readHeader(IOobject &, const fileName &, const word &typeName) const =0
Read object header from supplied file.
virtual word processorsDir(const IOobject &io) const
Actual name of processors dir (for use in mode PROCOBJECT,.
Namespace for OpenFOAM.
virtual mode_t mode(const fileName &, const bool checkVariants=true, const bool followLink=true) const =0
Return the file mode.