Add files necessary to run Expat configure.

[wxWidgets.git] / interface / wx / file.h

diff --git a/interface/wx/file.h b/interface/wx/file.h
index 2522be80e1d5b39b0794065d57fd8e538b8badcd..198fcc18cbf4b16d2ed27eee36aa036df15b6a83 100644 (file)
--- a/interface/wx/file.h
+++ b/interface/wx/file.h
@@ -3,63 +3,10 @@
 // Purpose:     interface of wxTempFile, wxFile
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxTempFile, wxFile
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 

-/**
-    We redefine these constants here because S_IREAD &c are _not_ standard
-    however, we do assume that the values correspond to the Unix umask bits.
-*/
-enum wxPosixPermissions
-{
-    /// standard Posix names for these permission flags
-    //@{
-    wxS_IRUSR = 00400,
-    wxS_IWUSR = 00200,
-    wxS_IXUSR = 00100,
-
-    wxS_IRGRP = 00040,
-    wxS_IWGRP = 00020,
-    wxS_IXGRP = 00010,
-
-    wxS_IROTH = 00004,
-    wxS_IWOTH = 00002,
-    wxS_IXOTH = 00001,
-    //@}
-
-    /// longer but more readable synonims for the constants above
-    //@{
-    wxPOSIX_USER_READ = wxS_IRUSR,
-    wxPOSIX_USER_WRITE = wxS_IWUSR,
-    wxPOSIX_USER_EXECUTE = wxS_IXUSR,
-
-    wxPOSIX_GROUP_READ = wxS_IRGRP,
-    wxPOSIX_GROUP_WRITE = wxS_IWGRP,
-    wxPOSIX_GROUP_EXECUTE = wxS_IXGRP,
-
-    wxPOSIX_OTHERS_READ = wxS_IROTH,
-    wxPOSIX_OTHERS_WRITE = wxS_IWOTH,
-    wxPOSIX_OTHERS_EXECUTE = wxS_IXOTH,
-    //@}
-
-    /// Default mode for the new files: allow reading/writing them to everybody but
-    /// the effective file mode will be set after anding this value with umask and
-    /// so won't include wxS_IW{GRP,OTH} for the default 022 umask value
-    wxS_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | \
-                   wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | \
-                   wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE),
-
-    /// Default mode for the new directories (see wxFileName::Mkdir): allow
-    /// reading/writing/executing them to everybody, but just like wxS_DEFAULT
-    /// the effective directory mode will be set after anding this value with umask
-    wxS_DIR_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | wxPOSIX_USER_EXECUTE | \
-                       wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | wxPOSIX_GROUP_EXECUTE | \
-                       wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE | wxPOSIX_OTHERS_EXECUTE)
-};
-
-
-

 /**
     @class wxTempFile
 
 /**
     @class wxTempFile
 


@@ -84,12 +31,12 @@ enum wxPosixPermissions
     file by default, you should explicitly call wxTempFile::Commit() to do it.
     Calling wxTempFile::Discard() explicitly discards any modifications: it
     closes and deletes the temporary file and leaves the original file unchanged.
     file by default, you should explicitly call wxTempFile::Commit() to do it.
     Calling wxTempFile::Discard() explicitly discards any modifications: it
     closes and deletes the temporary file and leaves the original file unchanged.

-    If you don't call neither of Commit() and Discard(), the destructor will
+    If you call neither Commit() nor Discard(), the destructor will

     call Discard() automatically.
 
     To summarize: if you want to replace another file, create an instance of
     call Discard() automatically.
 
     To summarize: if you want to replace another file, create an instance of

-    wxTempFile passing the name of the file to be replaced to the constructor
-    (you may also use default constructor and pass the file name to wxTempFile::Open).
+    wxTempFile passing the name of the file to be replaced to the constructor.
+    (You may also use default constructor and pass the file name to wxTempFile::Open.)

     Then you can write to wxTempFile using wxFile-like functions and later call
     wxTempFile::Commit() to replace the old file (and close this one) or call
     wxTempFile::Discard() to cancel the modifications.
     Then you can write to wxTempFile using wxFile-like functions and later call
     wxTempFile::Commit() to replace the old file (and close this one) or call
     wxTempFile::Discard() to cancel the modifications.


@@ -102,12 +49,14 @@ class wxTempFile
 public:
     /**
         Associates wxTempFile with the file to be replaced and opens it.
 public:
     /**
         Associates wxTempFile with the file to be replaced and opens it.

-        You should use IsOpened() to verify if the constructor succeeded.
+
+        @warning
+        You should use IsOpened() to verify that the constructor succeeded.

     */
     wxTempFile(const wxString& strName);
 
     /**
     */
     wxTempFile(const wxString& strName);
 
     /**

-        Destructor calls Discard() if temporary file is still opened.
+        Destructor calls Discard() if temporary file is still open.

     */
     ~wxTempFile();
 
     */
     ~wxTempFile();
 


@@ -116,17 +65,29 @@ public:
         file to the old name. Returns @true if both actions succeeded.
 
         If @false is returned it may unfortunately mean two quite different things:
         file to the old name. Returns @true if both actions succeeded.
 
         If @false is returned it may unfortunately mean two quite different things:

-        either that either the old file couldn't be deleted or that the new file
+        either that the old file couldn't be deleted or that the new file

         couldn't be renamed to the old name.
     */
     bool Commit();
 
     /**
         couldn't be renamed to the old name.
     */
     bool Commit();
 
     /**

-        Discard changes: the old file contents is not changed, temporary file is
-        deleted.
+        Discard changes: the old file contents are not changed, the temporary
+        file is deleted.

     */
     void Discard();
 
     */
     void Discard();
 

+    /**
+        Flush the data written to the file to disk.
+
+        This simply calls wxFile::Flush() for the underlying file and may be
+        necessary with file systems such as XFS and Ext4 under Linux. Calling
+        this function may however have serious performance implications and
+        also is not necessary with many other file systems so it is not done by
+        default -- but you can call it before calling Commit() to absolutely
+        ensure that the data was indeed written to the disk correctly.
+     */
+    bool Flush();
+

     /**
         Returns @true if the file was successfully opened.
     */
     /**
         Returns @true if the file was successfully opened.
     */


@@ -135,9 +96,8 @@ public:
     /**
         Returns the length of the file.
 
     /**
         Returns the length of the file.
 

-        This method may return wxInvalidOffset if the length couldn't be
-        determined or also 0 even for non-empty files if the file is not
-        seekable.
+        This method may return ::wxInvalidOffset if the length couldn't be
+        determined or 0 even for non-empty files if the file is not seekable.

 
         In general, the only way to determine if the file for which this function
         returns 0 is really empty or not is to try reading from it.
 
         In general, the only way to determine if the file for which this function
         returns 0 is really empty or not is to try reading from it.


@@ -161,7 +121,7 @@ public:
                       wxSeekMode mode = wxFromStart);
 
     /**
                       wxSeekMode mode = wxFromStart);
 
     /**

-        Returns the current position or wxInvalidOffset if file is not opened or
+        Returns the current position or ::wxInvalidOffset if file is not opened or

         if another error occurred.
     */
     wxFileOffset Tell() const;
         if another error occurred.
     */
     wxFileOffset Tell() const;


@@ -180,20 +140,11 @@ public:
 /**
     @class wxFile
 
 /**
     @class wxFile
 

-    A wxFile performs raw file I/O.
-
-    This is a very small class designed to minimize the overhead of using it - in fact,
-    there is hardly any overhead at all, but using it brings you automatic error
-    checking and hides differences between platforms and compilers.
-
-    wxFile also automatically closes the file in its destructor making it unnecessary
-    to worry about forgetting to do it.
-

     A wxFile performs raw file I/O. This is a very small class designed to
     minimize the overhead of using it - in fact, there is hardly any overhead at
     all, but using it brings you automatic error checking and hides differences
     between platforms and compilers. wxFile also automatically closes the file in
     A wxFile performs raw file I/O. This is a very small class designed to
     minimize the overhead of using it - in fact, there is hardly any overhead at
     all, but using it brings you automatic error checking and hides differences
     between platforms and compilers. wxFile also automatically closes the file in

-    its destructor making it unnecessary to worry about forgetting to do it.
+    its destructor so you won't forget to do so.

     wxFile is a wrapper around @c file descriptor. - see also wxFFile for a
     wrapper around @c FILE structure.
 
     wxFile is a wrapper around @c file descriptor. - see also wxFFile for a
     wrapper around @c FILE structure.
 


@@ -222,12 +173,12 @@ public:
             or test if it can be opened for writing with Access(). */
         write,
 
             or test if it can be opened for writing with Access(). */
         write,
 

-        /** Open file for reading and writing; can not be used with Access() */
+        /** Open file for reading and writing; cannot be used with Access() */

         read_write,
 
         /** Open file for appending: the file is opened for writing, but the old contents
         read_write,
 
         /** Open file for appending: the file is opened for writing, but the old contents

-            of the file is not erased and the file pointer is initially placed at the end
-            of the file; can not be used with Access().
+            of the file are not erased and the file pointer is initially placed at the end
+            of the file; cannot be used with Access().

 
             This is the same as OpenMode::write if the file doesn't exist.
         */
 
             This is the same as OpenMode::write if the file doesn't exist.
         */


@@ -258,6 +209,9 @@ public:
             The filename.
         @param mode
             The mode in which to open the file.
             The filename.
         @param mode
             The mode in which to open the file.

+
+        @warning
+        You should use IsOpened() to verify that the constructor succeeded.

     */
     wxFile(const wxString& filename,
            wxFile::OpenMode mode = wxFile::read);
     */
     wxFile(const wxString& filename,
            wxFile::OpenMode mode = wxFile::read);


@@ -273,10 +227,36 @@ public:
 
     /**
         Destructor will close the file.
 
     /**
         Destructor will close the file.

-        @note it is not virtual so you should not use wxFile polymorphically.
+        @note This destructor is not virtual so you should not use wxFile polymorphically.

     */
     ~wxFile();
 
     */
     ~wxFile();
 

+    /**
+        Returns the error code for the last unsuccessful operation.
+
+        The error code is system-dependent and corresponds to the value of the
+        standard @c errno variable when the last error occurred.
+
+        Notice that only simple accessors such as IsOpened() and Eof() (and
+        this method itself) don't modify the last error value, all other
+        methods can potentially change it if an error occurs, including the
+        const ones such as Tell() or Length().
+
+        @since 2.9.2
+
+        @see ClearLastError()
+    */
+    int GetLastError() const;
+
+    /**
+        Resets the error code.
+
+        GetLastError() will return 0 until the next error occurs.
+
+        @since 2.9.2
+    */
+    void ClearLastError();
+

     /**
         This function verifies if we may access the given file in specified mode.
         Only values of @c wxFile::read or @c wxFile::write really make sense here.
     /**
         This function verifies if we may access the given file in specified mode.
         Only values of @c wxFile::read or @c wxFile::write really make sense here.


@@ -285,7 +265,7 @@ public:
 
     /**
         Attaches an existing file descriptor to the wxFile object.
 
     /**
         Attaches an existing file descriptor to the wxFile object.

-        Example of predefined file descriptors are 0, 1 and 2 which correspond to
+        Examples of predefined file descriptors are 0, 1 and 2 which correspond to

         stdin, stdout and stderr (and have symbolic names of @c wxFile::fd_stdin,
         @c wxFile::fd_stdout and @c wxFile::fd_stderr).
 
         stdin, stdout and stderr (and have symbolic names of @c wxFile::fd_stdin,
         @c wxFile::fd_stdout and @c wxFile::fd_stderr).
 


@@ -297,7 +277,7 @@ public:
     /**
         Closes the file.
     */
     /**
         Closes the file.
     */

-    void Close();
+    bool Close();

 
     /**
         Creates a file for writing.
 
     /**
         Creates a file for writing.


@@ -321,7 +301,7 @@ public:
 
     /**
         Returns @true if the end of the file has been reached.
 
     /**
         Returns @true if the end of the file has been reached.

-        Note that the behaviour of the file pointer based class wxFFile is
+        Note that the behaviour of the file pointer-based class wxFFile is

         different as wxFFile::Eof() will return @true here only if an
         attempt has been made to read @b past the last byte of the file, while
         wxFile::Eof() will return @true even before such attempt is made if the
         different as wxFFile::Eof() will return @true here only if an
         attempt has been made to read @b past the last byte of the file, while
         wxFile::Eof() will return @true even before such attempt is made if the


@@ -329,7 +309,7 @@ public:
 
         Note also that this function doesn't work on unseekable file descriptors
         (examples include pipes, terminals and sockets under Unix) and an attempt to
 
         Note also that this function doesn't work on unseekable file descriptors
         (examples include pipes, terminals and sockets under Unix) and an attempt to

-        use it will result in an error message in such case.
+        use it will result in an error message.

 
         So, to read the entire file into memory, you should write a loop which uses
         Read() repeatedly and tests its return condition instead of using Eof()
 
         So, to read the entire file into memory, you should write a loop which uses
         Read() repeatedly and tests its return condition instead of using Eof()


@@ -339,7 +319,7 @@ public:
 
     /**
         Returns @true if the given name specifies an existing regular file
 
     /**
         Returns @true if the given name specifies an existing regular file

-        (not a directory or a link)
+        (not a directory or a link).

     */
     static bool Exists(const wxString& filename);
 
     */
     static bool Exists(const wxString& filename);
 


@@ -375,10 +355,9 @@ public:
         @param mode
             The mode in which to open the file.
         @param access
         @param mode
             The mode in which to open the file.
         @param access

-            An OR-combination of wxPosixPermissions enumeration values.
+            An OR-combination of ::wxPosixPermissions enumeration values.

     */
     */

-    bool Open(const wxString& filename,
-              wxFile::OpenMode mode = wxFile::read,
+    bool Open(const wxString& filename, wxFile::OpenMode mode = wxFile::read,

               int access = wxS_DEFAULT);
 
     /**
               int access = wxS_DEFAULT);
 
     /**


@@ -389,9 +368,26 @@ public:
         @param count
            Bytes to read
 
         @param count
            Bytes to read
 

-        @return The number of bytes read, or the symbol wxInvalidOffset.
+        @return The number of bytes read, or the symbol ::wxInvalidOffset.
+    */
+    ssize_t Read(void* buffer, size_t count);
+
+    /**
+        Reads the entire contents of the file into a string.
+
+        @param str
+            Non-@NULL pointer to a string to read data into.
+        @param conv
+            Conversion object to use in Unicode build; by default supposes
+            that file contents is encoded in UTF-8 but falls back to the
+            current locale encoding (or Latin-1 if it is UTF-8 too) if it is
+            not.
+
+        @return @true if file was read successfully, @false otherwise.
+
+        @since 2.9.5

     */
     */

-    size_t Read(void* buffer, size_t count);
+    bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto());

 
     /**
         Seeks to the specified position.
 
     /**
         Seeks to the specified position.


@@ -401,7 +397,7 @@ public:
         @param mode
             One of wxFromStart, wxFromEnd, wxFromCurrent.
 
         @param mode
             One of wxFromStart, wxFromEnd, wxFromCurrent.
 

-        @return The actual offset position achieved, or wxInvalidOffset on
+        @return The actual offset position achieved, or ::wxInvalidOffset on

                 failure.
     */
     wxFileOffset Seek(wxFileOffset ofs,
                 failure.
     */
     wxFileOffset Seek(wxFileOffset ofs,


@@ -415,13 +411,13 @@ public:
         @param ofs
             Number of bytes before the end of the file.
 
         @param ofs
             Number of bytes before the end of the file.
 

-        @return The actual offset position achieved, or wxInvalidOffset on
+        @return The actual offset position achieved, or ::wxInvalidOffset on

                 failure.
     */
     wxFileOffset SeekEnd(wxFileOffset ofs = 0);
 
     /**
                 failure.
     */
     wxFileOffset SeekEnd(wxFileOffset ofs = 0);
 
     /**

-        Returns the current position or wxInvalidOffset if file is not opened or
+        Returns the current position or ::wxInvalidOffset if file is not opened or

         if another error occurred.
     */
     wxFileOffset Tell() const;
         if another error occurred.
     */
     wxFileOffset Tell() const;