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