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