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