1//
2// File.h
3//
4// Library: Foundation
5// Package: Filesystem
6// Module: File
7//
8// Definition of the File class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef Foundation_File_INCLUDED
18#define Foundation_File_INCLUDED
19
20
21#include "Poco/Foundation.h"
22#include "Poco/Timestamp.h"
23#include <vector>
24
25
26#if defined(POCO_OS_FAMILY_WINDOWS)
27#if defined(_WIN32_WCE)
28#include "File_WINCE.h"
29#else
30#include "Poco/File_WIN32.h"
31#endif
32#elif defined(POCO_VXWORKS)
33#include "Poco/File_VX.h"
34#elif defined(POCO_OS_FAMILY_UNIX)
35#include "Poco/File_UNIX.h"
36#else
37#include "Poco/File_VMS.h"
38#endif
39
40
41namespace Poco {
42
43
44class Path;
45
46
47class Foundation_API File: private FileImpl
48 /// The File class provides methods for working with a file.
49 ///
50 /// Regarding paths passed to the various methods, note that
51 /// platform-specific limitations regarding maximum length
52 /// of the entire path and its components apply.
53 ///
54 /// On Windows, the implementation tries to work around the rather
55 /// low 260 characters MAX_PATH limit by adding the "\\?\" prefix if
56 /// a path is absolute and exceeds MAX_PATH characters in length.
57 /// Note that various limitations regarding usage of the "\\?\"
58 /// prefix apply in that case, e.g. the path must
59 /// not contain relative components ("." and "..") and must not
60 /// use the forward slash ("/") as directory separator.
61{
62public:
63 typedef FileSizeImpl FileSize;
64
65 File();
66 /// Creates the file.
67
68 File(const std::string& path);
69 /// Creates the file.
70
71 File(const char* path);
72 /// Creates the file.
73
74 File(const Path& path);
75 /// Creates the file.
76
77 File(const File& file);
78 /// Copy constructor.
79
80 virtual ~File();
81 /// Destroys the file.
82
83 File& operator = (const File& file);
84 /// Assignment operator.
85
86 File& operator = (const std::string& path);
87 /// Assignment operator.
88
89 File& operator = (const char* path);
90 /// Assignment operator.
91
92 File& operator = (const Path& path);
93 /// Assignment operator.
94
95 void swap(File& file);
96 /// Swaps the file with another one.
97
98 const std::string& path() const;
99 /// Returns the path.
100
101 bool exists() const;
102 /// Returns true iff the file exists.
103
104 bool canRead() const;
105 /// Returns true iff the file is readable.
106
107 bool canWrite() const;
108 /// Returns true iff the file is writeable.
109
110 bool canExecute() const;
111 /// Returns true iff the file is executable.
112 ///
113 /// On Windows and OpenVMS, the file must have
114 /// the extension ".EXE" to be executable.
115 /// On Unix platforms, the executable permission
116 /// bit must be set.
117
118 bool isFile() const;
119 /// Returns true iff the file is a regular file.
120
121 bool isLink() const;
122 /// Returns true iff the file is a symbolic link.
123
124 bool isDirectory() const;
125 /// Returns true iff the file is a directory.
126
127 bool isDevice() const;
128 /// Returns true iff the file is a device.
129
130 bool isHidden() const;
131 /// Returns true if the file is hidden.
132 ///
133 /// On Windows platforms, the file's hidden
134 /// attribute is set for this to be true.
135 ///
136 /// On Unix platforms, the file name must
137 /// begin with a period for this to be true.
138
139 Timestamp created() const;
140 /// Returns the creation date of the file.
141 ///
142 /// Not all platforms or filesystems (e.g. Linux and most Unix
143 /// platforms with the exception of FreeBSD and Mac OS X)
144 /// maintain the creation date of a file.
145 /// On such platforms, created() returns
146 /// the time of the last inode modification.
147
148 Timestamp getLastModified() const;
149 /// Returns the modification date of the file.
150
151 File& setLastModified(const Timestamp& ts);
152 /// Sets the modification date of the file.
153
154 FileSize getSize() const;
155 /// Returns the size of the file in bytes.
156
157 File& setSize(FileSize size);
158 /// Sets the size of the file in bytes. Can be used
159 /// to truncate a file.
160
161 File& setWriteable(bool flag = true);
162 /// Makes the file writeable (if flag is true), or
163 /// non-writeable (if flag is false) by setting the
164 /// file's flags in the filesystem accordingly.
165
166 File& setReadOnly(bool flag = true);
167 /// Makes the file non-writeable (if flag is true), or
168 /// writeable (if flag is false) by setting the
169 /// file's flags in the filesystem accordingly.
170
171 File& setExecutable(bool flag = true);
172 /// Makes the file executable (if flag is true), or
173 /// non-executable (if flag is false) by setting
174 /// the file's permission bits accordingly.
175 ///
176 /// Does nothing on Windows and OpenVMS.
177
178 void copyTo(const std::string& path) const;
179 /// Copies the file (or directory) to the given path.
180 /// The target path can be a directory.
181 ///
182 /// A directory is copied recursively.
183
184 void moveTo(const std::string& path);
185 /// Copies the file (or directory) to the given path and
186 /// removes the original file. The target path can be a directory.
187
188 void renameTo(const std::string& path);
189 /// Renames the file to the new name.
190
191 void remove(bool recursive = false);
192 /// Deletes the file. If recursive is true and the
193 /// file is a directory, recursively deletes all
194 /// files in the directory.
195
196 bool createFile();
197 /// Creates a new, empty file in an atomic operation.
198 /// Returns true if the file has been created and false
199 /// if the file already exists. Throws an exception if
200 /// an error occurs.
201
202 bool createDirectory();
203 /// Creates a directory. Returns true if the directory
204 /// has been created and false if it already exists.
205 /// Throws an exception if an error occurs.
206
207 void createDirectories();
208 /// Creates a directory (and all parent directories
209 /// if necessary).
210
211 void list(std::vector<std::string>& files) const;
212 /// Fills the vector with the names of all
213 /// files in the directory.
214
215 void list(std::vector<File>& files) const;
216 /// Fills the vector with the names of all
217 /// files in the directory.
218
219 FileSize totalSpace() const;
220 /// Returns the total size in bytes of the partition containing this path.
221
222 FileSize usableSpace() const;
223 /// Returns the number of usable free bytes on the partition containing this path.
224
225 FileSize freeSpace() const;
226 /// Returns the number of free bytes on the partition containing this path.
227
228 bool operator == (const File& file) const;
229 bool operator != (const File& file) const;
230 bool operator < (const File& file) const;
231 bool operator <= (const File& file) const;
232 bool operator > (const File& file) const;
233 bool operator >= (const File& file) const;
234
235 static void handleLastError(const std::string& path);
236 /// For internal use only. Throws an appropriate
237 /// exception for the last file-related error.
238
239protected:
240 void copyDirectory(const std::string& path) const;
241 /// Copies a directory. Used internally by copyTo().
242};
243
244
245//
246// inlines
247//
248inline const std::string& File::path() const
249{
250 return getPathImpl();
251}
252
253
254inline bool File::operator == (const File& file) const
255{
256 return getPathImpl() == file.getPathImpl();
257}
258
259
260inline bool File::operator != (const File& file) const
261{
262 return getPathImpl() != file.getPathImpl();
263}
264
265
266inline bool File::operator < (const File& file) const
267{
268 return getPathImpl() < file.getPathImpl();
269}
270
271
272inline bool File::operator <= (const File& file) const
273{
274 return getPathImpl() <= file.getPathImpl();
275}
276
277
278inline bool File::operator > (const File& file) const
279{
280 return getPathImpl() > file.getPathImpl();
281}
282
283
284inline bool File::operator >= (const File& file) const
285{
286 return getPathImpl() >= file.getPathImpl();
287}
288
289
290inline void swap(File& f1, File& f2)
291{
292 f1.swap(f2);
293}
294
295
296} // namespace Poco
297
298
299#endif // Foundation_File_INCLUDED
300