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