docs/latex/wx/file.tex

   1 \section{\class{wxFile}}\label{wxfile}
   2
   3 A wxFile performs raw file I/O. This is a very small class designed to
   4 minimize the overhead of using it - in fact, there is hardly any overhead at
   5 all, but using it brings you automatic error checking and hides differences
   6 between platforms and compilers.
   7
   8 \wxheading{Derived from}
   9
  10 None.
  11
  12 \wxheading{Include files}
  13
  14 <wx/file.h>
  15
  16 \wxheading{Constants}
  17
  18 wx/file.h defines the following constants:
  19
  20 {\small
  21 \begin{verbatim}
  22 #define wxS_IRUSR 00400
  23 #define wxS_IWUSR 00200
  24 #define wxS_IXUSR 00100
  25
  26 #define wxS_IRGRP 00040
  27 #define wxS_IWGRP 00020
  28 #define wxS_IXGRP 00010
  29
  30 #define wxS_IROTH 00004
  31 #define wxS_IWOTH 00002
  32 #define wxS_IXOTH 00001
  33
  34 // default mode for the new files: corresponds to umask 022
  35 #define wxS_DEFAULT  (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH)
  36 \end{verbatim}
  37 }
  38
  39 These constants define the file access rights and are used with
  40 \helpref{wxFile::Create}{wxfilecreate} and \helpref{wxFile::Open}{wxfileopen}.
  41
  42 The {\it OpenMode} enumeration defines the different modes for opening a file,
  43 it's defined inside wxFile class so its members should be specified with {\it wxFile::} scope
  44 resolution prefix. It is also used with \helpref{wxFile::Access}{wxfileaccess} function.
  45
  46 \twocolwidtha{7cm}
  47 \begin{twocollist}\itemsep=0pt%
  48 \twocolitem{{\bf wxFile::read}}{Open file for reading or test if it can be opened for reading with Access()}
  49 \twocolitem{{\bf wxFile::write}}{Open file for writing deleting the contents of the file if it already exists
  50 or test if it can be opened for writing with Access()}
  51 \twocolitem{{\bf wxFile::read\_write}}{Open file for reading and writing; can not be used with Access()}
  52 \twocolitem{{\bf wxFile::write\_append}}{Open file for appending: the file is opened for writing, but the old
  53 contents of the file is not erased and the file pointer is initially placed at the end of the file;
  54 can not be used with Access()}
  55 \end{twocollist}
  56
  57 Other constants defined elsewhere but used by wxFile functions are wxInvalidOffset which represents an
  58 invalid value of type {\it off\_t} and is returned by functions returning {\it off\_t} on error and the seek
  59 mode constants used with \helpref{Seek()}{wxfileseek}:
  60
  61 \twocolwidtha{7cm}
  62 \begin{twocollist}\itemsep=0pt%
  63 \twocolitem{{\bf wxFromStart}}{Count offset from the start of the file}
  64 \twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer}
  65 \twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)}
  66 \end{twocollist}
  67
  68 \latexignore{\rtfignore{\wxheading{Members}}}
  69
  70 \membersection{wxFile::wxFile}\label{wxfileconstr}
  71
  72 \func{}{wxFile}{\void}
  73
  74 Default constructor.
  75
  76 \func{}{wxFile}{\param{const char*}{ filename}, \param{wxFile::OpenMode}{ mode = wxFile::read}}
  77
  78 Opens a file with the given mode. As there is no way to return whether the
  79 operation was successful or not from the constructor you should test the
  80 return value of \helpref{IsOpened}{wxfileisopened} to check that it didn't
  81 fail.
  82
  83 \func{}{wxFile}{\param{int}{ fd}}
  84
  85 Opens a file with the given file descriptor, which has already been opened.
  86
  87 \wxheading{Parameters}
  88
  89 \docparam{filename}{The filename.}
  90
  91 \docparam{mode}{The mode in which to open the file. May be one of {\bf wxFile::read}, {\bf wxFile::write} and {\bf wxFile::read\_write}.}
  92
  93 \docparam{fd}{An existing file descriptor (see \helpref{Attach()}{wxfileattach} for the list of predefined descriptors)}
  94
  95 \membersection{wxFile::\destruct{wxFile}}
  96
  97 \func{}{\destruct{wxFile}}{\void}
  98
  99 Destructor will close the file.
 100
 101 NB: it is not virtual so you should {\it not} derive from wxFile!
 102
 103 \membersection{wxFile::Access}\label{wxfileaccess}
 104
 105 \func{static bool}{Access}{\param{const char *}{ name}, \param{OpenMode}{ mode}}
 106
 107 This function verifies if we may access the given file in specified mode. Only
 108 values of wxFile::read or wxFile::write really make sense here.
 109
 110 \membersection{wxFile::Attach}\label{wxfileattach}
 111
 112 \func{void}{Attach}{\param{int}{ fd}}
 113
 114 Attaches an existing file descriptor to the wxFile object. Example of predefined
 115 file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr (and
 116 have symbolic names of wxFile::fd\_stdin, wxFile::fd\_stdout and wxFile::fd\_stderr).
 117
 118 The descriptor should be already opened and it will be closed by wxFile
 119 object.
 120
 121 \membersection{wxFile::Close}\label{wxfileclose}
 122
 123 \func{void}{Close}{\void}
 124
 125 Closes the file.
 126
 127 \membersection{wxFile::Create}\label{wxfilecreate}
 128
 129 \func{bool}{Create}{\param{const char*}{ filename}, \param{bool}{ overwrite = FALSE}, \param{int }{access = wxS\_DEFAULT}}
 130
 131 Creates a file for writing. If the file already exists, setting {\bf overwrite} to TRUE
 132 will ensure it is overwritten.
 133
 134 \membersection{wxFile::Detach}\label{wxfiledetach}
 135
 136 \func{void}{Detach}{\void}
 137
 138 Get back a file descriptor from wxFile object - the caller is responsible for closing the file if this
 139 descriptor is opened. \helpref{IsOpened()}{wxfileisopened} will return FALSE after call to Detach().
 140
 141 \membersection{wxFile::fd}\label{wxfilefd}
 142
 143 \constfunc{int}{fd}{\void}
 144
 145 Returns the file descriptor associated with the file.
 146
 147 \membersection{wxFile::Eof}\label{wxfileeof}
 148
 149 \constfunc{bool}{Eof}{\void}
 150
 151 Returns TRUE if the end of the file has been reached.
 152
 153 \membersection{wxFile::Exists}\label{wxfileexists}
 154
 155 \func{static bool}{Exists}{\param{const char*}{ filename}}
 156
 157 Returns TRUE if the given name specifies an existing regular file.
 158
 159 \membersection{wxFile::Flush}\label{wxfileflush}
 160
 161 \func{bool}{Flush}{\void}
 162
 163 Flushes the file descriptor.
 164
 165 Note that wxFile::Flush is not implemented on some Windows compilers
 166 due to a missing fsync function, which reduces the usefulness of this function
 167 (it can still be called but it will do nothing on unsupported compilers).
 168
 169 \membersection{wxFile::IsOpened}\label{wxfileisopened}
 170
 171 \constfunc{bool}{IsOpened}{\void}
 172
 173 Returns TRUE if the file has been opened.
 174
 175 \membersection{wxFile::Length}\label{wxfilelength}
 176
 177 \constfunc{off\_t}{Length}{\void}
 178
 179 Returns the length of the file.
 180
 181 \membersection{wxFile::Open}\label{wxfileopen}
 182
 183 \func{bool}{Open}{\param{const char*}{ filename}, \param{wxFile::OpenMode}{ mode = wxFile::read}}
 184
 185 Opens the file, returning TRUE if successful.
 186
 187 \wxheading{Parameters}
 188
 189 \docparam{filename}{The filename.}
 190
 191 \docparam{mode}{The mode in which to open the file. May be one of {\bf wxFile::read}, {\bf wxFile::write} and {\bf wxFile::read\_write}.}
 192
 193 \membersection{wxFile::Read}\label{wxfileread}
 194
 195 \func{off\_t}{Read}{\param{void*}{ buffer}, \param{off\_t}{ count}}
 196
 197 Reads the specified number of bytes into a buffer, returning the actual number read.
 198
 199 \wxheading{Parameters}
 200
 201 \docparam{buffer}{A buffer to receive the data.}
 202
 203 \docparam{count}{The number of bytes to read.}
 204
 205 \wxheading{Return value}
 206
 207 The number of bytes read, or the symbol {\bf wxInvalidOffset} (-1) if there was an error.
 208
 209 \membersection{wxFile::Seek}\label{wxfileseek}
 210
 211 \func{off\_t}{Seek}{\param{off\_t }{ofs}, \param{wxFile::SeekMode }{mode = wxFile::FromStart}}
 212
 213 Seeks to the specified position.
 214
 215 \wxheading{Parameters}
 216
 217 \docparam{ofs}{Offset to seek to.}
 218
 219 \docparam{mode}{One of {\bf wxFile::FromStart}, {\bf wxFile::FromEnd}, {\bf wxFile::FromCurrent}.}
 220
 221 \wxheading{Return value}
 222
 223 The actual offset position achieved, or wxInvalidOffset on failure.
 224
 225 \membersection{wxFile::SeekEnd}\label{wxfileseekend}
 226
 227 \func{off\_t}{SeekEnd}{\param{off\_t }{ofs = 0}}
 228
 229 Moves the file pointer to the specified number of bytes before the end of the file.
 230
 231 \wxheading{Parameters}
 232
 233 \docparam{ofs}{Number of bytes before the end of the file.}
 234
 235 \wxheading{Return value}
 236
 237 The actual offset position achieved, or wxInvalidOffset on failure.
 238
 239 \membersection{wxFile::Tell}\label{wxfiletell}
 240
 241 \constfunc{off\_t}{Tell}{\void}
 242
 243 Returns the current position or wxInvalidOffset if file is not opened or if another
 244 error occured.
 245
 246 \membersection{wxFile::Write}\label{wxfilewrite}
 247
 248 \func{bool}{Write}{\param{const void*}{ buffer}, \param{off\_t}{ count}}
 249
 250 Writes the specified number of bytes from a buffer.
 251
 252 \wxheading{Parameters}
 253
 254 \docparam{buffer}{A buffer containing the data.}
 255
 256 \docparam{count}{The number of bytes to write.}
 257
 258 \wxheading{Return value}
 259
 260 TRUE if the operation was successful.
 261
 262 \membersection{wxFile::Write}\label{wxfilewrites}
 263
 264 \func{bool}{Write}{\param{const wxString\& }{s}}
 265
 266 Writes the contents of the string to the file, returns TRUE on success.
 267