X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/842d6c94bd9fedff4799fd8e54cdb48de2fa7aa3..b0ee47ff76c278c053ac2ad36bb3129b0fcd050f:/docs/latex/wx/file.tex?ds=sidebyside

diff --git a/docs/latex/wx/file.tex b/docs/latex/wx/file.tex
index 655f48fcd4..fa8a9c8bdf 100644
--- a/docs/latex/wx/file.tex
+++ b/docs/latex/wx/file.tex
@@ -3,7 +3,10 @@
 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.
+between platforms and compilers. wxFile also automatically closes the file in
+its destructor making it unnecessary to worry about forgetting to do it.
+wxFile is a wrapper around {\tt file descriptor.} - see also 
+\helpref{wxFFile}{wxffile} for a wrapper around {\tt FILE} structure.
 
 \wxheading{Derived from}
 
@@ -17,7 +20,6 @@ None.
 
 wx/file.h defines the following constants:
 
-{\small
 \begin{verbatim}
 #define wxS_IRUSR 00400
 #define wxS_IWUSR 00200
@@ -34,13 +36,12 @@ wx/file.h defines the following constants:
 // default mode for the new files: corresponds to umask 022
 #define wxS_DEFAULT  (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH)
 \end{verbatim}
-}
 
 These constants define the file access rights and are used with 
 \helpref{wxFile::Create}{wxfilecreate} and \helpref{wxFile::Open}{wxfileopen}.
 
 The {\it OpenMode} enumeration defines the different modes for opening a file,
-it's defined inside wxFile class so its members should be specified with {\it wxFile::} scope
+it is defined inside wxFile class so its members should be specified with {\it wxFile::} scope
 resolution prefix. It is also used with \helpref{wxFile::Access}{wxfileaccess} function.
 
 \twocolwidtha{7cm}
@@ -51,7 +52,8 @@ or test if it can be opened for writing with Access()}
 \twocolitem{{\bf wxFile::read\_write}}{Open file for reading and writing; can not be used with Access()}
 \twocolitem{{\bf wxFile::write\_append}}{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()}
+can not be used with Access(). This is the same as {\bf wxFile::write} if the
+file doesn't exist.}
 \end{twocollist}
 
 Other constants defined elsewhere but used by wxFile functions are wxInvalidOffset which represents an
@@ -82,7 +84,7 @@ fail.
 
 \func{}{wxFile}{\param{int}{ fd}}
 
-Opens a file with the given file descriptor, which has already been opened.
+Associates the file with the given file descriptor, which has already been opened.
 
 \wxheading{Parameters}
 
@@ -98,7 +100,7 @@ Opens a file with the given file descriptor, which has already been opened.
 
 Destructor will close the file.
 
-NB: it is not virtual so you should {\it not} derive from wxFile!
+NB: it is not virtual so you should use wxFile polymorphically.
 
 \membersection{wxFile::Access}\label{wxfileaccess}
 
@@ -113,7 +115,7 @@ values of wxFile::read or wxFile::write really make sense here.
 
 Attaches an existing file descriptor to the wxFile object. Example of predefined
 file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr (and
-have symbolic names of wxFile::fd\_stdin, wxFile::fd\_stdout and wxFile::fd\_stderr).
+have symbolic names of {\bf wxFile::fd\_stdin}, {\bf wxFile::fd\_stdout} and {\bf wxFile::fd\_stderr}).
 
 The descriptor should be already opened and it will be closed by wxFile
 object.
@@ -148,18 +150,28 @@ Returns the file descriptor associated with the file.
 
 \constfunc{bool}{Eof}{\void}
 
-Returns TRUE if the end of the file has been reached (the last byte has been read).
+Returns TRUE if the end of the file has been reached.
 
-Note that the behaviour of the file pointer based class
-\helpref{wxFFile}{wxffile} is different as \helpref{wxFFile::Eof}{wxffileeof}
-will return TRUE here only if an attempt has been made to read
-{\it past} the last byte of the file.
+Note that the behaviour of the file pointer based class 
+\helpref{wxFFile}{wxffile} is different as \helpref{wxFFile::Eof}{wxffileeof} 
+will return TRUE here only if an attempt has been made to read 
+{\it past} the last byte of the file, while wxFile::Eof() will return TRUE
+even before such attempt is made if the file pointer is at the last position
+in the file.
+
+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. So, to read the entire
+file into memory, you should write a loop which uses 
+\helpref{Read}{wxfileread} repeatedly and tests its return condition instead
+of using Eof() as this will not work for special files under Unix.
 
 \membersection{wxFile::Exists}\label{wxfileexists}
 
 \func{static bool}{Exists}{\param{const char*}{ filename}}
 
-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)
 
 \membersection{wxFile::Flush}\label{wxfileflush}
 
@@ -246,11 +258,11 @@ The actual offset position achieved, or wxInvalidOffset on failure.
 \constfunc{off\_t}{Tell}{\void}
 
 Returns the current position or wxInvalidOffset if file is not opened or if another
-error occured.
+error occurred.
 
 \membersection{wxFile::Write}\label{wxfilewrite}
 
-\func{bool}{Write}{\param{const void*}{ buffer}, \param{off\_t}{ count}}
+\func{size\_t}{Write}{\param{const void*}{ buffer}, \param{off\_t}{ count}}
 
 Writes the specified number of bytes from a buffer.
 
@@ -262,20 +274,24 @@ Writes the specified number of bytes from a buffer.
 
 \wxheading{Return value}
 
-TRUE if the operation was successful.
+the number of bytes actually written
 
 \membersection{wxFile::Write}\label{wxfilewrites}
 
-\func{bool}{Write}{\param{const wxString\& }{s}}
+\func{bool}{Write}{\param{const wxString\& }{s}, \param{wxMBConv&}{ conv = wxConvLibc}}
 
 Writes the contents of the string to the file, returns TRUE on success.
 
+The second argument is only meaningful in Unicode build of wxWindows when
+{\it conv} is used to convert {\it s} to multibyte representation.
+
 \section{\class{wxFFile}}\label{wxffile}
 
-A wxFFile performs raw file I/O. This is a very small class designed to
+wxFFile implements buffered 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.
+between platforms and compilers. It wraps inside it a {\tt FILE *} handle used
+by standard C IO library (also known as {\tt stdio}).
 
 \wxheading{Derived from}
 
@@ -315,7 +331,10 @@ Opens a file with the given file pointer, which has already been opened.
 
 \docparam{filename}{The filename.}
 
-\docparam{mode}{The mode in which to open the file using standard C strings.}
+\docparam{mode}{The mode in which to open the file using standard C strings.
+Note that you should use {\tt "b"} flag if you use binary files under Windows
+or the results might be unexpected due to automatic newline conversion done
+for the text files.}
 
 \docparam{fp}{An existing file descriptor, such as stderr.}
 
@@ -444,7 +463,7 @@ Returns the current position.
 
 \membersection{wxFFile::Write}\label{wxffilewrite}
 
-\func{size_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}}
+\func{size\_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}}
 
 Writes the specified number of bytes from a buffer.
 
@@ -460,7 +479,9 @@ Number of bytes written.
 
 \membersection{wxFFile::Write}\label{wxffilewrites}
 
-\func{bool}{Write}{\param{const wxString\& }{s}}
+\func{bool}{Write}{\param{const wxString\& }{s}, \param{wxMBConv&}{ conv = wxConvLibc}}
 
 Writes the contents of the string to the file, returns TRUE on success.
 
+The second argument is only meaningful in Unicode build of wxWindows when
+{\it conv} is used to convert {\it s} to multibyte representation.