Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: file.h | |
0b70c946 | 3 | // Purpose: interface of wxTempFile, wxFile |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
526954c5 | 6 | // Licence: wxWindows licence |
23324ae1 FM |
7 | ///////////////////////////////////////////////////////////////////////////// |
8 | ||
23b7f0cb | 9 | |
23324ae1 FM |
10 | /** |
11 | @class wxTempFile | |
7c913512 | 12 | |
23324ae1 FM |
13 | wxTempFile provides a relatively safe way to replace the contents of the |
14 | existing file. The name is explained by the fact that it may be also used as | |
15 | just a temporary file if you don't replace the old file contents. | |
7c913512 | 16 | |
23324ae1 | 17 | Usually, when a program replaces the contents of some file it first opens it for |
23b7f0cb FM |
18 | writing, thus losing all of the old data and then starts recreating it. |
19 | This approach is not very safe because during the regeneration of the file bad | |
20 | things may happen: the program may find that there is an internal error preventing | |
21 | it from completing file generation, the user may interrupt it (especially if file | |
23324ae1 FM |
22 | generation takes long time) and, finally, any other external interrupts (power |
23 | supply failure or a disk error) will leave you without either the original file | |
24 | or the new one. | |
7c913512 | 25 | |
23324ae1 FM |
26 | wxTempFile addresses this problem by creating a temporary file which is meant to |
27 | replace the original file - but only after it is fully written. So, if the user | |
28 | interrupts the program during the file generation, the old file won't be lost. | |
29 | Also, if the program discovers itself that it doesn't want to replace the old | |
30 | file there is no problem - in fact, wxTempFile will @b not replace the old | |
23b7f0cb FM |
31 | file by default, you should explicitly call wxTempFile::Commit() to do it. |
32 | Calling wxTempFile::Discard() explicitly discards any modifications: it | |
33 | closes and deletes the temporary file and leaves the original file unchanged. | |
9cfebe8c | 34 | If you call neither Commit() nor Discard(), the destructor will |
23b7f0cb | 35 | call Discard() automatically. |
7c913512 | 36 | |
23324ae1 | 37 | To summarize: if you want to replace another file, create an instance of |
9cfebe8c FM |
38 | wxTempFile passing the name of the file to be replaced to the constructor. |
39 | (You may also use default constructor and pass the file name to wxTempFile::Open.) | |
23b7f0cb FM |
40 | Then you can write to wxTempFile using wxFile-like functions and later call |
41 | wxTempFile::Commit() to replace the old file (and close this one) or call | |
42 | wxTempFile::Discard() to cancel the modifications. | |
7c913512 | 43 | |
23324ae1 FM |
44 | @library{wxbase} |
45 | @category{file} | |
46 | */ | |
7c913512 | 47 | class wxTempFile |
23324ae1 FM |
48 | { |
49 | public: | |
50 | /** | |
23b7f0cb | 51 | Associates wxTempFile with the file to be replaced and opens it. |
57bf907d FM |
52 | |
53 | @warning | |
9cfebe8c | 54 | You should use IsOpened() to verify that the constructor succeeded. |
23324ae1 FM |
55 | */ |
56 | wxTempFile(const wxString& strName); | |
57 | ||
58 | /** | |
9cfebe8c | 59 | Destructor calls Discard() if temporary file is still open. |
23324ae1 FM |
60 | */ |
61 | ~wxTempFile(); | |
62 | ||
63 | /** | |
64 | Validate changes: deletes the old file of name m_strName and renames the new | |
23b7f0cb FM |
65 | file to the old name. Returns @true if both actions succeeded. |
66 | ||
67 | If @false is returned it may unfortunately mean two quite different things: | |
9cfebe8c | 68 | either that the old file couldn't be deleted or that the new file |
23b7f0cb | 69 | couldn't be renamed to the old name. |
23324ae1 FM |
70 | */ |
71 | bool Commit(); | |
72 | ||
73 | /** | |
9cfebe8c FM |
74 | Discard changes: the old file contents are not changed, the temporary |
75 | file is deleted. | |
23324ae1 FM |
76 | */ |
77 | void Discard(); | |
78 | ||
f1a73c6a VZ |
79 | /** |
80 | Flush the data written to the file to disk. | |
81 | ||
82 | This simply calls wxFile::Flush() for the underlying file and may be | |
83 | necessary with file systems such as XFS and Ext4 under Linux. Calling | |
84 | this function may however have serious performance implications and | |
85 | also is not necessary with many other file systems so it is not done by | |
86 | default -- but you can call it before calling Commit() to absolutely | |
87 | ensure that the data was indeed written to the disk correctly. | |
88 | */ | |
89 | bool Flush(); | |
90 | ||
23324ae1 FM |
91 | /** |
92 | Returns @true if the file was successfully opened. | |
93 | */ | |
328f5751 | 94 | bool IsOpened() const; |
23324ae1 FM |
95 | |
96 | /** | |
97 | Returns the length of the file. | |
41f6f17d | 98 | |
acdad9db | 99 | This method may return ::wxInvalidOffset if the length couldn't be |
9cfebe8c | 100 | determined or 0 even for non-empty files if the file is not seekable. |
23b7f0cb FM |
101 | |
102 | In general, the only way to determine if the file for which this function | |
103 | returns 0 is really empty or not is to try reading from it. | |
23324ae1 | 104 | */ |
328f5751 | 105 | wxFileOffset Length() const; |
23324ae1 FM |
106 | |
107 | /** | |
108 | Open the temporary file, returns @true on success, @false if an error | |
109 | occurred. | |
4cc4bfaf | 110 | @a strName is the name of file to be replaced. The temporary file is always |
23b7f0cb FM |
111 | created in the directory where @a strName is. In particular, if @a strName |
112 | doesn't include the path, it is created in the current directory and the | |
113 | program should have write access to it for the function to succeed. | |
23324ae1 FM |
114 | */ |
115 | bool Open(const wxString& strName); | |
116 | ||
117 | /** | |
118 | Seeks to the specified position. | |
119 | */ | |
120 | wxFileOffset Seek(wxFileOffset ofs, | |
121 | wxSeekMode mode = wxFromStart); | |
122 | ||
123 | /** | |
acdad9db | 124 | Returns the current position or ::wxInvalidOffset if file is not opened or |
23b7f0cb | 125 | if another error occurred. |
23324ae1 | 126 | */ |
328f5751 | 127 | wxFileOffset Tell() const; |
23324ae1 FM |
128 | |
129 | /** | |
130 | Write to the file, return @true on success, @false on failure. | |
23324ae1 | 131 | The second argument is only meaningful in Unicode build of wxWidgets when |
4cc4bfaf | 132 | @a conv is used to convert @a str to multibyte representation. |
23324ae1 FM |
133 | */ |
134 | bool Write(const wxString& str, | |
135 | const wxMBConv& conv = wxConvUTF8); | |
136 | }; | |
137 | ||
138 | ||
e54c96f1 | 139 | |
23324ae1 FM |
140 | /** |
141 | @class wxFile | |
7c913512 | 142 | |
23324ae1 FM |
143 | A wxFile performs raw file I/O. This is a very small class designed to |
144 | minimize the overhead of using it - in fact, there is hardly any overhead at | |
145 | all, but using it brings you automatic error checking and hides differences | |
146 | between platforms and compilers. wxFile also automatically closes the file in | |
9cfebe8c | 147 | its destructor so you won't forget to do so. |
23b7f0cb FM |
148 | wxFile is a wrapper around @c file descriptor. - see also wxFFile for a |
149 | wrapper around @c FILE structure. | |
7c913512 | 150 | |
23b7f0cb FM |
151 | ::wxFileOffset is used by the wxFile functions which require offsets as |
152 | parameter or return them. If the platform supports it, wxFileOffset is a | |
153 | typedef for a native 64 bit integer, otherwise a 32 bit integer is used for | |
154 | ::wxFileOffset. | |
7c913512 | 155 | |
23324ae1 FM |
156 | @library{wxbase} |
157 | @category{file} | |
158 | */ | |
7c913512 | 159 | class wxFile |
23324ae1 FM |
160 | { |
161 | public: | |
23b7f0cb | 162 | |
23324ae1 | 163 | /** |
23b7f0cb FM |
164 | The OpenMode enumeration defines the different modes for opening a file with wxFile. |
165 | It is also used with wxFile::Access function. | |
c1d97593 | 166 | */ |
23b7f0cb FM |
167 | enum OpenMode { |
168 | ||
169 | /** Open file for reading or test if it can be opened for reading with Access() */ | |
170 | read, | |
171 | ||
172 | /** Open file for writing deleting the contents of the file if it already exists | |
173 | or test if it can be opened for writing with Access(). */ | |
174 | write, | |
175 | ||
4c51a665 | 176 | /** Open file for reading and writing; cannot be used with Access() */ |
23b7f0cb FM |
177 | read_write, |
178 | ||
179 | /** Open file for appending: the file is opened for writing, but the old contents | |
9cfebe8c | 180 | of the file are not erased and the file pointer is initially placed at the end |
4c51a665 | 181 | of the file; cannot be used with Access(). |
23b7f0cb FM |
182 | |
183 | This is the same as OpenMode::write if the file doesn't exist. | |
184 | */ | |
185 | write_append, | |
186 | ||
187 | /** | |
188 | Open the file securely for writing (Uses O_EXCL | O_CREAT). | |
189 | Will fail if the file already exists, else create and open it atomically. | |
190 | Useful for opening temporary files without being vulnerable to race exploits. | |
191 | */ | |
192 | write_excl | |
193 | }; | |
194 | ||
195 | /** | |
c1d97593 RR |
196 | Standard file descriptors |
197 | */ | |
198 | enum { fd_invalid = -1, fd_stdin, fd_stdout, fd_stderr }; | |
199 | ||
23b7f0cb | 200 | /** |
c1d97593 RR |
201 | Default constructor. |
202 | */ | |
203 | wxFile(); | |
23b7f0cb | 204 | |
c1d97593 RR |
205 | /** |
206 | Opens a file with a filename. | |
3c4f71cc | 207 | |
7c913512 | 208 | @param filename |
4cc4bfaf | 209 | The filename. |
7c913512 | 210 | @param mode |
23b7f0cb | 211 | The mode in which to open the file. |
57bf907d FM |
212 | |
213 | @warning | |
214 | You should use IsOpened() to verify that the constructor succeeded. | |
23324ae1 | 215 | */ |
7c913512 FM |
216 | wxFile(const wxString& filename, |
217 | wxFile::OpenMode mode = wxFile::read); | |
23b7f0cb | 218 | |
c1d97593 RR |
219 | /** |
220 | Associates the file with the given file descriptor, which has already been | |
221 | opened. See Attach() for the list of predefined descriptors. | |
23b7f0cb | 222 | |
c1d97593 | 223 | @param fd |
23b7f0cb | 224 | An existing file descriptor. |
c1d97593 | 225 | */ |
7c913512 | 226 | wxFile(int fd); |
23324ae1 FM |
227 | |
228 | /** | |
229 | Destructor will close the file. | |
9cfebe8c | 230 | @note This destructor is not virtual so you should not use wxFile polymorphically. |
23324ae1 FM |
231 | */ |
232 | ~wxFile(); | |
233 | ||
65fe93d8 VZ |
234 | /** |
235 | Returns the error code for the last unsuccessful operation. | |
236 | ||
237 | The error code is system-dependent and corresponds to the value of the | |
238 | standard @c errno variable when the last error occurred. | |
239 | ||
240 | Notice that only simple accessors such as IsOpened() and Eof() (and | |
241 | this method itself) don't modify the last error value, all other | |
242 | methods can potentially change it if an error occurs, including the | |
243 | const ones such as Tell() or Length(). | |
244 | ||
245 | @since 2.9.2 | |
246 | ||
247 | @see ClearLastError() | |
248 | */ | |
249 | int GetLastError() const; | |
250 | ||
251 | /** | |
252 | Resets the error code. | |
253 | ||
254 | GetLastError() will return 0 until the next error occurs. | |
255 | ||
256 | @since 2.9.2 | |
257 | */ | |
258 | void ClearLastError(); | |
259 | ||
23324ae1 | 260 | /** |
c1d97593 RR |
261 | This function verifies if we may access the given file in specified mode. |
262 | Only values of @c wxFile::read or @c wxFile::write really make sense here. | |
23324ae1 | 263 | */ |
23b7f0cb | 264 | static bool Access(const wxString& name, wxFile::OpenMode mode); |
23324ae1 FM |
265 | |
266 | /** | |
23b7f0cb | 267 | Attaches an existing file descriptor to the wxFile object. |
9cfebe8c | 268 | Examples of predefined file descriptors are 0, 1 and 2 which correspond to |
23b7f0cb | 269 | stdin, stdout and stderr (and have symbolic names of @c wxFile::fd_stdin, |
c1d97593 | 270 | @c wxFile::fd_stdout and @c wxFile::fd_stderr). |
23b7f0cb | 271 | |
23324ae1 FM |
272 | The descriptor should be already opened and it will be closed by wxFile |
273 | object. | |
274 | */ | |
275 | void Attach(int fd); | |
276 | ||
277 | /** | |
278 | Closes the file. | |
279 | */ | |
5267aefd | 280 | bool Close(); |
23324ae1 FM |
281 | |
282 | /** | |
23b7f0cb FM |
283 | Creates a file for writing. |
284 | ||
285 | If the file already exists, setting @b overwrite to @true will ensure | |
286 | it is overwritten. | |
287 | ||
f41d6c8c FM |
288 | @a access may be an OR combination of the ::wxPosixPermissions enumeration |
289 | values. | |
23324ae1 | 290 | */ |
23b7f0cb FM |
291 | bool Create(const wxString& filename, |
292 | bool overwrite = false, | |
23324ae1 FM |
293 | int access = wxS_DEFAULT); |
294 | ||
295 | /** | |
296 | Get back a file descriptor from wxFile object - the caller is responsible for | |
23b7f0cb FM |
297 | closing the file if this descriptor is opened. |
298 | IsOpened() will return @false after call to Detach(). | |
23324ae1 FM |
299 | */ |
300 | void Detach(); | |
301 | ||
302 | /** | |
303 | Returns @true if the end of the file has been reached. | |
9cfebe8c | 304 | Note that the behaviour of the file pointer-based class wxFFile is |
23b7f0cb | 305 | different as wxFFile::Eof() will return @true here only if an |
c1d97593 RR |
306 | attempt has been made to read @b past the last byte of the file, while |
307 | wxFile::Eof() will return @true even before such attempt is made if the | |
308 | file pointer is at the last position in the file. | |
23b7f0cb | 309 | |
23324ae1 FM |
310 | Note also that this function doesn't work on unseekable file descriptors |
311 | (examples include pipes, terminals and sockets under Unix) and an attempt to | |
9cfebe8c | 312 | use it will result in an error message. |
23b7f0cb FM |
313 | |
314 | So, to read the entire file into memory, you should write a loop which uses | |
315 | Read() repeatedly and tests its return condition instead of using Eof() | |
316 | as this will not work for special files under Unix. | |
23324ae1 | 317 | */ |
328f5751 | 318 | bool Eof() const; |
23324ae1 FM |
319 | |
320 | /** | |
23b7f0cb | 321 | Returns @true if the given name specifies an existing regular file |
9cfebe8c | 322 | (not a directory or a link). |
23324ae1 FM |
323 | */ |
324 | static bool Exists(const wxString& filename); | |
325 | ||
326 | /** | |
327 | Flushes the file descriptor. | |
23b7f0cb FM |
328 | |
329 | Note that Flush() is not implemented on some Windows compilers due to a | |
330 | missing fsync function, which reduces the usefulness of this function | |
23324ae1 FM |
331 | (it can still be called but it will do nothing on unsupported compilers). |
332 | */ | |
333 | bool Flush(); | |
334 | ||
335 | /** | |
23b7f0cb | 336 | Returns the type of the file. |
23324ae1 | 337 | */ |
328f5751 | 338 | wxFileKind GetKind() const; |
23324ae1 FM |
339 | |
340 | /** | |
341 | Returns @true if the file has been opened. | |
342 | */ | |
328f5751 | 343 | bool IsOpened() const; |
23324ae1 FM |
344 | |
345 | /** | |
346 | Returns the length of the file. | |
347 | */ | |
328f5751 | 348 | wxFileOffset Length() const; |
23324ae1 FM |
349 | |
350 | /** | |
351 | Opens the file, returning @true if successful. | |
3c4f71cc | 352 | |
7c913512 | 353 | @param filename |
4cc4bfaf | 354 | The filename. |
7c913512 | 355 | @param mode |
23b7f0cb | 356 | The mode in which to open the file. |
f41d6c8c | 357 | @param access |
992ff331 | 358 | An OR-combination of ::wxPosixPermissions enumeration values. |
23324ae1 | 359 | */ |
5267aefd | 360 | bool Open(const wxString& filename, wxFile::OpenMode mode = wxFile::read, |
f41d6c8c | 361 | int access = wxS_DEFAULT); |
23324ae1 | 362 | |
23324ae1 | 363 | /** |
23b7f0cb FM |
364 | Reads from the file into a memory buffer. |
365 | ||
c1d97593 RR |
366 | @param buffer |
367 | Buffer to write in | |
368 | @param count | |
23b7f0cb FM |
369 | Bytes to read |
370 | ||
acdad9db | 371 | @return The number of bytes read, or the symbol ::wxInvalidOffset. |
23324ae1 | 372 | */ |
5267aefd | 373 | ssize_t Read(void* buffer, size_t count); |
23324ae1 FM |
374 | |
375 | /** | |
376 | Seeks to the specified position. | |
3c4f71cc | 377 | |
7c913512 | 378 | @param ofs |
4cc4bfaf | 379 | Offset to seek to. |
7c913512 | 380 | @param mode |
4cc4bfaf | 381 | One of wxFromStart, wxFromEnd, wxFromCurrent. |
3c4f71cc | 382 | |
acdad9db | 383 | @return The actual offset position achieved, or ::wxInvalidOffset on |
23b7f0cb | 384 | failure. |
23324ae1 FM |
385 | */ |
386 | wxFileOffset Seek(wxFileOffset ofs, | |
387 | wxSeekMode mode = wxFromStart); | |
388 | ||
389 | /** | |
23b7f0cb FM |
390 | Moves the file pointer to the specified number of bytes relative to the |
391 | end of the file. For example, @c SeekEnd(-5) would position the pointer 5 | |
23324ae1 | 392 | bytes before the end. |
3c4f71cc | 393 | |
7c913512 | 394 | @param ofs |
4cc4bfaf | 395 | Number of bytes before the end of the file. |
3c4f71cc | 396 | |
acdad9db | 397 | @return The actual offset position achieved, or ::wxInvalidOffset on |
23b7f0cb | 398 | failure. |
23324ae1 FM |
399 | */ |
400 | wxFileOffset SeekEnd(wxFileOffset ofs = 0); | |
401 | ||
402 | /** | |
acdad9db | 403 | Returns the current position or ::wxInvalidOffset if file is not opened or |
23b7f0cb | 404 | if another error occurred. |
23324ae1 | 405 | */ |
328f5751 | 406 | wxFileOffset Tell() const; |
23324ae1 | 407 | |
c1d97593 RR |
408 | /** |
409 | Write data to the file (descriptor). | |
23b7f0cb | 410 | |
4050e98d | 411 | @param buffer |
c1d97593 RR |
412 | Buffer from which to read data |
413 | @param count | |
414 | Number of bytes to write | |
23b7f0cb | 415 | |
c1d97593 RR |
416 | @return The number of bytes written. |
417 | */ | |
418 | size_t Write(const void *buffer, size_t count); | |
419 | ||
23324ae1 FM |
420 | /** |
421 | Writes the contents of the string to the file, returns @true on success. | |
23324ae1 | 422 | The second argument is only meaningful in Unicode build of wxWidgets when |
c1d97593 | 423 | @a conv is used to convert @a s to a multibyte representation. |
23b7f0cb | 424 | |
23324ae1 | 425 | Note that this method only works with @c NUL-terminated strings, if you want |
7c913512 | 426 | to write data with embedded @c NULs to the file you should use the other |
c1d97593 | 427 | Write() overload. |
23324ae1 FM |
428 | */ |
429 | bool Write(const wxString& s, const wxMBConv& conv = wxConvUTF8); | |
430 | ||
431 | /** | |
432 | Returns the file descriptor associated with the file. | |
433 | */ | |
328f5751 | 434 | int fd() const; |
23324ae1 | 435 | }; |
e54c96f1 | 436 |