interface/wx/file.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        file.h
   3 // Purpose:     interface of wxTempFile, wxFile
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxTempFile
  12
  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.
  16
  17     Usually, when a program replaces the contents of some file it first opens it for
  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
  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.
  25
  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
  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.
  34     If you call neither Commit() nor Discard(), the destructor will
  35     call Discard() automatically.
  36
  37     To summarize: if you want to replace another file, create an instance of
  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.)
  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.
  43
  44     @library{wxbase}
  45     @category{file}
  46 */
  47 class wxTempFile
  48 {
  49 public:
  50     /**
  51         Associates wxTempFile with the file to be replaced and opens it.
  52
  53         @warning
  54         You should use IsOpened() to verify that the constructor succeeded.
  55     */
  56     wxTempFile(const wxString& strName);
  57
  58     /**
  59         Destructor calls Discard() if temporary file is still open.
  60     */
  61     ~wxTempFile();
  62
  63     /**
  64         Validate changes: deletes the old file of name m_strName and renames the new
  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:
  68         either that the old file couldn't be deleted or that the new file
  69         couldn't be renamed to the old name.
  70     */
  71     bool Commit();
  72
  73     /**
  74         Discard changes: the old file contents are not changed, the temporary
  75         file is deleted.
  76     */
  77     void Discard();
  78
  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
  91     /**
  92         Returns @true if the file was successfully opened.
  93     */
  94     bool IsOpened() const;
  95
  96     /**
  97         Returns the length of the file.
  98
  99         This method may return ::wxInvalidOffset if the length couldn't be
 100         determined or 0 even for non-empty files if the file is not seekable.
 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.
 104     */
 105     wxFileOffset Length() const;
 106
 107     /**
 108         Open the temporary file, returns @true on success, @false if an error
 109         occurred.
 110         @a strName is the name of file to be replaced. The temporary file is always
 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.
 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     /**
 124         Returns the current position or ::wxInvalidOffset if file is not opened or
 125         if another error occurred.
 126     */
 127     wxFileOffset Tell() const;
 128
 129     /**
 130         Write to the file, return @true on success, @false on failure.
 131         The second argument is only meaningful in Unicode build of wxWidgets when
 132         @a conv is used to convert @a str to multibyte representation.
 133     */
 134     bool Write(const wxString& str,
 135                const wxMBConv& conv = wxConvUTF8);
 136 };
 137
 138
 139
 140 /**
 141     @class wxFile
 142
 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
 147     its destructor so you won't forget to do so.
 148     wxFile is a wrapper around @c file descriptor. - see also wxFFile for a
 149     wrapper around @c FILE structure.
 150
 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.
 155
 156     @library{wxbase}
 157     @category{file}
 158 */
 159 class wxFile
 160 {
 161 public:
 162
 163     /**
 164         The OpenMode enumeration defines the different modes for opening a file with wxFile.
 165         It is also used with wxFile::Access function.
 166     */
 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
 176         /** Open file for reading and writing; cannot be used with Access() */
 177         read_write,
 178
 179         /** Open file for appending: the file is opened for writing, but the old contents
 180             of the file are not erased and the file pointer is initially placed at the end
 181             of the file; cannot be used with Access().
 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     /**
 196        Standard file descriptors
 197     */
 198     enum { fd_invalid = -1, fd_stdin, fd_stdout, fd_stderr };
 199
 200     /**
 201        Default constructor.
 202     */
 203     wxFile();
 204
 205     /**
 206         Opens a file with a filename.
 207
 208         @param filename
 209             The filename.
 210         @param mode
 211             The mode in which to open the file.
 212
 213         @warning
 214         You should use IsOpened() to verify that the constructor succeeded.
 215     */
 216     wxFile(const wxString& filename,
 217            wxFile::OpenMode mode = wxFile::read);
 218
 219     /**
 220         Associates the file with the given file descriptor, which has already been
 221         opened. See Attach() for the list of predefined descriptors.
 222
 223         @param fd
 224             An existing file descriptor.
 225     */
 226     wxFile(int fd);
 227
 228     /**
 229         Destructor will close the file.
 230         @note This destructor is not virtual so you should not use wxFile polymorphically.
 231     */
 232     ~wxFile();
 233
 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
 260     /**
 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.
 263     */
 264     static bool Access(const wxString& name, wxFile::OpenMode mode);
 265
 266     /**
 267         Attaches an existing file descriptor to the wxFile object.
 268         Examples of predefined file descriptors are 0, 1 and 2 which correspond to
 269         stdin, stdout and stderr (and have symbolic names of @c wxFile::fd_stdin,
 270         @c wxFile::fd_stdout and @c wxFile::fd_stderr).
 271
 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     */
 280     bool Close();
 281
 282     /**
 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
 288         @a access may be an OR combination of the ::wxPosixPermissions enumeration
 289         values.
 290     */
 291     bool Create(const wxString& filename,
 292                 bool overwrite = false,
 293                 int access = wxS_DEFAULT);
 294
 295     /**
 296         Get back a file descriptor from wxFile object - the caller is responsible for
 297         closing the file if this descriptor is opened.
 298         IsOpened() will return @false after call to Detach().
 299     */
 300     void Detach();
 301
 302     /**
 303         Returns @true if the end of the file has been reached.
 304         Note that the behaviour of the file pointer-based class wxFFile is
 305         different as wxFFile::Eof() will return @true here only if an
 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.
 309
 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
 312         use it will result in an error message.
 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.
 317     */
 318     bool Eof() const;
 319
 320     /**
 321         Returns @true if the given name specifies an existing regular file
 322         (not a directory or a link).
 323     */
 324     static bool Exists(const wxString& filename);
 325
 326     /**
 327         Flushes the file descriptor.
 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
 331         (it can still be called but it will do nothing on unsupported compilers).
 332     */
 333     bool Flush();
 334
 335     /**
 336         Returns the type of the file.
 337     */
 338     wxFileKind GetKind() const;
 339
 340     /**
 341         Returns @true if the file has been opened.
 342     */
 343     bool IsOpened() const;
 344
 345     /**
 346         Returns the length of the file.
 347     */
 348     wxFileOffset Length() const;
 349
 350     /**
 351         Opens the file, returning @true if successful.
 352
 353         @param filename
 354             The filename.
 355         @param mode
 356             The mode in which to open the file.
 357         @param access
 358             An OR-combination of ::wxPosixPermissions enumeration values.
 359     */
 360     bool Open(const wxString& filename, wxFile::OpenMode mode = wxFile::read,
 361               int access = wxS_DEFAULT);
 362
 363     /**
 364         Reads from the file into a memory buffer.
 365
 366         @param buffer
 367            Buffer to write in
 368         @param count
 369            Bytes to read
 370
 371         @return The number of bytes read, or the symbol ::wxInvalidOffset.
 372     */
 373     ssize_t Read(void* buffer, size_t count);
 374
 375     /**
 376         Reads the entire contents of the file into a string.
 377
 378         @param str
 379             Non-@NULL pointer to a string to read data into.
 380         @param conv
 381             Conversion object to use in Unicode build; by default supposes
 382             that file contents is encoded in UTF-8 but falls back to the
 383             current locale encoding (or Latin-1 if it is UTF-8 too) if it is
 384             not.
 385
 386         @return @true if file was read successfully, @false otherwise.
 387
 388         @since 2.9.5
 389     */
 390     bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto());
 391
 392     /**
 393         Seeks to the specified position.
 394
 395         @param ofs
 396             Offset to seek to.
 397         @param mode
 398             One of wxFromStart, wxFromEnd, wxFromCurrent.
 399
 400         @return The actual offset position achieved, or ::wxInvalidOffset on
 401                 failure.
 402     */
 403     wxFileOffset Seek(wxFileOffset ofs,
 404                       wxSeekMode mode = wxFromStart);
 405
 406     /**
 407         Moves the file pointer to the specified number of bytes relative to the
 408         end of the file. For example, @c SeekEnd(-5) would position the pointer 5
 409         bytes before the end.
 410
 411         @param ofs
 412             Number of bytes before the end of the file.
 413
 414         @return The actual offset position achieved, or ::wxInvalidOffset on
 415                 failure.
 416     */
 417     wxFileOffset SeekEnd(wxFileOffset ofs = 0);
 418
 419     /**
 420         Returns the current position or ::wxInvalidOffset if file is not opened or
 421         if another error occurred.
 422     */
 423     wxFileOffset Tell() const;
 424
 425     /**
 426        Write data to the file (descriptor).
 427
 428        @param buffer
 429           Buffer from which to read data
 430        @param count
 431          Number of bytes to write
 432
 433        @return The number of bytes written.
 434     */
 435     size_t Write(const void *buffer, size_t count);
 436
 437     /**
 438         Writes the contents of the string to the file, returns @true on success.
 439         The second argument is only meaningful in Unicode build of wxWidgets when
 440         @a conv is used to convert @a s to a multibyte representation.
 441
 442         Note that this method only works with @c NUL-terminated strings, if you want
 443         to write data with embedded @c NULs to the file you should use the other
 444         Write() overload.
 445     */
 446     bool Write(const wxString& s, const wxMBConv& conv = wxConvUTF8);
 447
 448     /**
 449         Returns the file descriptor associated with the file.
 450     */
 451     int fd() const;
 452 };
 453