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 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         Flush the data written to the file to disk.
 134
 135         This simply calls wxFile::Flush() for the underlying file and may be
 136         necessary with file systems such as XFS and Ext4 under Linux. Calling
 137         this function may however have serious performance implications and
 138         also is not necessary with many other file systems so it is not done by
 139         default -- but you can call it before calling Commit() to absolutely
 140         ensure that the data was indeed written to the disk correctly.
 141      */
 142     bool Flush();
 143
 144     /**
 145         Returns @true if the file was successfully opened.
 146     */
 147     bool IsOpened() const;
 148
 149     /**
 150         Returns the length of the file.
 151
 152         This method may return ::wxInvalidOffset if the length couldn't be
 153         determined or 0 even for non-empty files if the file is not seekable.
 154
 155         In general, the only way to determine if the file for which this function
 156         returns 0 is really empty or not is to try reading from it.
 157     */
 158     wxFileOffset Length() const;
 159
 160     /**
 161         Open the temporary file, returns @true on success, @false if an error
 162         occurred.
 163         @a strName is the name of file to be replaced. The temporary file is always
 164         created in the directory where @a strName is. In particular, if @a strName
 165         doesn't include the path, it is created in the current directory and the
 166         program should have write access to it for the function to succeed.
 167     */
 168     bool Open(const wxString& strName);
 169
 170     /**
 171         Seeks to the specified position.
 172     */
 173     wxFileOffset Seek(wxFileOffset ofs,
 174                       wxSeekMode mode = wxFromStart);
 175
 176     /**
 177         Returns the current position or ::wxInvalidOffset if file is not opened or
 178         if another error occurred.
 179     */
 180     wxFileOffset Tell() const;
 181
 182     /**
 183         Write to the file, return @true on success, @false on failure.
 184         The second argument is only meaningful in Unicode build of wxWidgets when
 185         @a conv is used to convert @a str to multibyte representation.
 186     */
 187     bool Write(const wxString& str,
 188                const wxMBConv& conv = wxConvUTF8);
 189 };
 190
 191
 192
 193 /**
 194     @class wxFile
 195
 196     A wxFile performs raw file I/O. This is a very small class designed to
 197     minimize the overhead of using it - in fact, there is hardly any overhead at
 198     all, but using it brings you automatic error checking and hides differences
 199     between platforms and compilers. wxFile also automatically closes the file in
 200     its destructor so you won't forget to do so.
 201     wxFile is a wrapper around @c file descriptor. - see also wxFFile for a
 202     wrapper around @c FILE structure.
 203
 204     ::wxFileOffset is used by the wxFile functions which require offsets as
 205     parameter or return them. If the platform supports it, wxFileOffset is a
 206     typedef for a native 64 bit integer, otherwise a 32 bit integer is used for
 207     ::wxFileOffset.
 208
 209     @library{wxbase}
 210     @category{file}
 211 */
 212 class wxFile
 213 {
 214 public:
 215
 216     /**
 217         The OpenMode enumeration defines the different modes for opening a file with wxFile.
 218         It is also used with wxFile::Access function.
 219     */
 220     enum OpenMode {
 221
 222         /** Open file for reading or test if it can be opened for reading with Access() */
 223         read,
 224
 225         /** Open file for writing deleting the contents of the file if it already exists
 226             or test if it can be opened for writing with Access(). */
 227         write,
 228
 229         /** Open file for reading and writing; can not be used with Access() */
 230         read_write,
 231
 232         /** Open file for appending: the file is opened for writing, but the old contents
 233             of the file are not erased and the file pointer is initially placed at the end
 234             of the file; can not be used with Access().
 235
 236             This is the same as OpenMode::write if the file doesn't exist.
 237         */
 238         write_append,
 239
 240         /**
 241             Open the file securely for writing (Uses O_EXCL | O_CREAT).
 242             Will fail if the file already exists, else create and open it atomically.
 243             Useful for opening temporary files without being vulnerable to race exploits.
 244         */
 245         write_excl
 246     };
 247
 248     /**
 249        Standard file descriptors
 250     */
 251     enum { fd_invalid = -1, fd_stdin, fd_stdout, fd_stderr };
 252
 253     /**
 254        Default constructor.
 255     */
 256     wxFile();
 257
 258     /**
 259         Opens a file with a filename.
 260
 261         @param filename
 262             The filename.
 263         @param mode
 264             The mode in which to open the file.
 265
 266         @warning
 267         You should use IsOpened() to verify that the constructor succeeded.
 268     */
 269     wxFile(const wxString& filename,
 270            wxFile::OpenMode mode = wxFile::read);
 271
 272     /**
 273         Associates the file with the given file descriptor, which has already been
 274         opened. See Attach() for the list of predefined descriptors.
 275
 276         @param fd
 277             An existing file descriptor.
 278     */
 279     wxFile(int fd);
 280
 281     /**
 282         Destructor will close the file.
 283         @note This destructor is not virtual so you should not use wxFile polymorphically.
 284     */
 285     ~wxFile();
 286
 287     /**
 288         This function verifies if we may access the given file in specified mode.
 289         Only values of @c wxFile::read or @c wxFile::write really make sense here.
 290     */
 291     static bool Access(const wxString& name, wxFile::OpenMode mode);
 292
 293     /**
 294         Attaches an existing file descriptor to the wxFile object.
 295         Examples of predefined file descriptors are 0, 1 and 2 which correspond to
 296         stdin, stdout and stderr (and have symbolic names of @c wxFile::fd_stdin,
 297         @c wxFile::fd_stdout and @c wxFile::fd_stderr).
 298
 299         The descriptor should be already opened and it will be closed by wxFile
 300         object.
 301     */
 302     void Attach(int fd);
 303
 304     /**
 305         Closes the file.
 306     */
 307     bool Close();
 308
 309     /**
 310         Creates a file for writing.
 311
 312         If the file already exists, setting @b overwrite to @true will ensure
 313         it is overwritten.
 314
 315         @a access may be an OR combination of the ::wxPosixPermissions enumeration
 316         values.
 317     */
 318     bool Create(const wxString& filename,
 319                 bool overwrite = false,
 320                 int access = wxS_DEFAULT);
 321
 322     /**
 323         Get back a file descriptor from wxFile object - the caller is responsible for
 324         closing the file if this descriptor is opened.
 325         IsOpened() will return @false after call to Detach().
 326     */
 327     void Detach();
 328
 329     /**
 330         Returns @true if the end of the file has been reached.
 331         Note that the behaviour of the file pointer-based class wxFFile is
 332         different as wxFFile::Eof() will return @true here only if an
 333         attempt has been made to read @b past the last byte of the file, while
 334         wxFile::Eof() will return @true even before such attempt is made if the
 335         file pointer is at the last position in the file.
 336
 337         Note also that this function doesn't work on unseekable file descriptors
 338         (examples include pipes, terminals and sockets under Unix) and an attempt to
 339         use it will result in an error message.
 340
 341         So, to read the entire file into memory, you should write a loop which uses
 342         Read() repeatedly and tests its return condition instead of using Eof()
 343         as this will not work for special files under Unix.
 344     */
 345     bool Eof() const;
 346
 347     /**
 348         Returns @true if the given name specifies an existing regular file
 349         (not a directory or a link).
 350     */
 351     static bool Exists(const wxString& filename);
 352
 353     /**
 354         Flushes the file descriptor.
 355
 356         Note that Flush() is not implemented on some Windows compilers due to a
 357         missing fsync function, which reduces the usefulness of this function
 358         (it can still be called but it will do nothing on unsupported compilers).
 359     */
 360     bool Flush();
 361
 362     /**
 363         Returns the type of the file.
 364     */
 365     wxFileKind GetKind() const;
 366
 367     /**
 368         Returns @true if the file has been opened.
 369     */
 370     bool IsOpened() const;
 371
 372     /**
 373         Returns the length of the file.
 374     */
 375     wxFileOffset Length() const;
 376
 377     /**
 378         Opens the file, returning @true if successful.
 379
 380         @param filename
 381             The filename.
 382         @param mode
 383             The mode in which to open the file.
 384         @param access
 385             An OR-combination of ::wxPosixPermissions enumeration values.
 386     */
 387     bool Open(const wxString& filename, wxFile::OpenMode mode = wxFile::read,
 388               int access = wxS_DEFAULT);
 389
 390     /**
 391         Reads from the file into a memory buffer.
 392
 393         @param buffer
 394            Buffer to write in
 395         @param count
 396            Bytes to read
 397
 398         @return The number of bytes read, or the symbol ::wxInvalidOffset.
 399     */
 400     ssize_t Read(void* buffer, size_t count);
 401
 402     /**
 403         Seeks to the specified position.
 404
 405         @param ofs
 406             Offset to seek to.
 407         @param mode
 408             One of wxFromStart, wxFromEnd, wxFromCurrent.
 409
 410         @return The actual offset position achieved, or ::wxInvalidOffset on
 411                 failure.
 412     */
 413     wxFileOffset Seek(wxFileOffset ofs,
 414                       wxSeekMode mode = wxFromStart);
 415
 416     /**
 417         Moves the file pointer to the specified number of bytes relative to the
 418         end of the file. For example, @c SeekEnd(-5) would position the pointer 5
 419         bytes before the end.
 420
 421         @param ofs
 422             Number of bytes before the end of the file.
 423
 424         @return The actual offset position achieved, or ::wxInvalidOffset on
 425                 failure.
 426     */
 427     wxFileOffset SeekEnd(wxFileOffset ofs = 0);
 428
 429     /**
 430         Returns the current position or ::wxInvalidOffset if file is not opened or
 431         if another error occurred.
 432     */
 433     wxFileOffset Tell() const;
 434
 435     /**
 436        Write data to the file (descriptor).
 437
 438        @param buffer
 439           Buffer from which to read data
 440        @param count
 441          Number of bytes to write
 442
 443        @return The number of bytes written.
 444     */
 445     size_t Write(const void *buffer, size_t count);
 446
 447     /**
 448         Writes the contents of the string to the file, returns @true on success.
 449         The second argument is only meaningful in Unicode build of wxWidgets when
 450         @a conv is used to convert @a s to a multibyte representation.
 451
 452         Note that this method only works with @c NUL-terminated strings, if you want
 453         to write data with embedded @c NULs to the file you should use the other
 454         Write() overload.
 455     */
 456     bool Write(const wxString& s, const wxMBConv& conv = wxConvUTF8);
 457
 458     /**
 459         Returns the file descriptor associated with the file.
 460     */
 461     int fd() const;
 462 };
 463