interface/wx/file.h

   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 */
  46 class wxTempFile
  47 {
  48 public:
  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 */
 158 class wxFile
 159 {
 160 public:
 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