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 {\small
  16 \begin{verbatim}
  17 #define wxS_IRUSR 00400
  18 #define wxS_IWUSR 00200
  19 #define wxS_IXUSR 00100
  20
  21 #define wxS_IRGRP 00040
  22 #define wxS_IWGRP 00020
  23 #define wxS_IXGRP 00010
  24
  25 #define wxS_IROTH 00004
  26 #define wxS_IWOTH 00002
  27 #define wxS_IXOTH 00001
  28
  29 // default mode for the new files: corresponds to umask 022
  30 #define wxS_DEFAULT  (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH)
  31 \end{verbatim}
  32 }
  33
  34 These constants define the file access rights and are used with
  35 \helpref{wxFile::Create}{wxfilecreate} and \helpref{wxFile::Open}{wxfileopen}.
  36
  37 The {\it OpenMode} enumeration defines the different modes for opening a file,
  38 it's defined inside wxFile class so its members should be specified with {\it
  39 wxFile::} scope resolution prefix. It is also used with
  40 \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 \func{static bool}{Access}{\param{const char *}{ name}, \param{OpenMode}{ mode}
 101
 102 This function verifies if we may access the given file in specified mode. Only
 103 values of wxFile::read or wxFile::write really make sense here.
 104
 105 \membersection{wxFile::Attach}\label{wxfileattach}
 106 \func{void}{Attach}{\param{int}{ fd}}
 107
 108 Attaches an existing file descriptor to the wxFile object. Example of predefined
 109 file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr (and
 110 have symbolic names of wxFile::fd\_stdin, wxFile::fd\_stdout and wxFile::fd\_stderr).
 111
 112 The descriptor should be already opened and it will be closed by wxFile
 113 object.
 114
 115 \membersection{wxFile::Close}\label{wxfileclose}
 116
 117 \func{void}{Close}{\void}
 118
 119 Closes the file.
 120
 121 \membersection{wxFile::Create}\label{wxfilecreate}
 122
 123 \func{bool}{Create}{\param{const char*}{ filename}, \param{bool}{ overwrite = FALSE}, \param{int }{access = wxS\_DEFAULT}}
 124
 125 Creates a file for writing. If the file already exists, setting {\bf overwrite} to TRUE
 126 will ensure it is overwritten.
 127
 128 \membersection{wxFile::Detach}\label{wxfiledetach}
 129 \func{void}{Detach}{\void}
 130
 131 Get back a file descriptor from wxFile object - the caller is responsible for closing the file if this
 132 descriptor is opened. \helpref{IsOpened()}{wxfileisopened} will return FALSE after call to Detach().
 133
 134 \membersection{wxFile::fd}\label{wxfilefd}
 135 \constfunc{int}{fd}{\void}
 136
 137 Returns the file descriptor associated with the file.
 138
 139 \membersection{wxFile::Eof}\label{wxfileeof}
 140
 141 \constfunc{bool}{Eof}{\void}
 142
 143 Returns TRUE if the end of the file has been reached.
 144
 145 \membersection{wxFile::Exists}\label{wxfileexists}
 146
 147 \func{static bool}{Exists}{\param{const char*}{ filename}}
 148
 149 Returns TRUE if the given name specifies an existing regular file.
 150
 151 \membersection{wxFile::Flush}\label{wxfileflush}
 152
 153 \func{bool}{Flush}{\void}
 154
 155 Flushes the file descriptor.
 156
 157 Note that wxFile::Flush is not implemented on some Windows compilers
 158 due to a missing fsync function, which reduces the usefulness of this function
 159 (it can still be called but it will do nothing on unsupported compilers).
 160
 161 \membersection{wxFile::IsOpened}\label{wxfileisopened}
 162
 163 \constfunc{bool}{IsOpened}{\void}
 164
 165 Returns TRUE if the file has been opened.
 166
 167 \membersection{wxFile::Length}\label{wxfilelength}
 168
 169 \constfunc{off\_t}{Length}{\void}
 170
 171 Returns the length of the file.
 172
 173 \membersection{wxFile::Open}\label{wxfileopen}
 174
 175 \func{bool}{Open}{\param{const char*}{ filename}, \param{wxFile::OpenMode}{ mode = wxFile::read}}
 176
 177 Opens the file, returning TRUE if successful.
 178
 179 \wxheading{Parameters}
 180
 181 \docparam{filename}{The filename.}
 182
 183 \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}.}
 184
 185 \membersection{wxFile::Read}\label{wxfileread}
 186
 187 \func{off\_t}{Read}{\param{void*}{ buffer}, \param{off\_t}{ count}}
 188
 189 Reads the specified number of bytes into a buffer, returning the actual number read.
 190
 191 \wxheading{Parameters}
 192
 193 \docparam{buffer}{A buffer to receive the data.}
 194
 195 \docparam{count}{The number of bytes to read.}
 196
 197 \wxheading{Return value}
 198
 199 The number of bytes read, or the symbol {\bf wxInvalidOffset} (-1) if there was an error.
 200
 201 \membersection{wxFile::Seek}\label{wxfileseek}
 202
 203 \func{off\_t}{Seek}{\param{off\_t }{ofs}, \param{wxFile::SeekMode }{mode = wxFile::FromStart}}
 204
 205 Seeks to the specified position.
 206
 207 \wxheading{Parameters}
 208
 209 \docparam{ofs}{Offset to seek to.}
 210
 211 \docparam{mode}{One of {\bf wxFile::FromStart}, {\bf wxFile::FromEnd}, {\bf wxFile::FromCurrent}.}
 212
 213 \wxheading{Return value}
 214
 215 The actual offset position achieved, or wxInvalidOffset on failure.
 216
 217 \membersection{wxFile::SeekEnd}\label{wxfileseekend}
 218
 219 \func{off\_t}{SeekEnd}{\param{off\_t }{ofs = 0}}
 220
 221 Moves the file pointer to the specified number of bytes before the end of the file.
 222
 223 \wxheading{Parameters}
 224
 225 \docparam{ofs}{Number of bytes before the end of the file.}
 226
 227 \wxheading{Return value}
 228
 229 The actual offset position achieved, or wxInvalidOffset on failure.
 230
 231 \membersection{wxFile::Tell}\label{wxfiletell}
 232
 233 \constfunc{off\_t}{Tell}{\void}
 234
 235 Returns the current position or wxInvalidOffset if file is not opened or if another
 236 error occured.
 237
 238 \membersection{wxFile::Write}\label{wxfilewrite}
 239
 240 \func{bool}{Write}{\param{const void*}{ buffer}, \param{off\_t}{ count}}
 241
 242 Writes the specified number of bytes from a buffer.
 243
 244 \wxheading{Parameters}
 245
 246 \docparam{buffer}{A buffer containing the data.}
 247
 248 \docparam{count}{The number of bytes to write.}
 249
 250 \wxheading{Return value}
 251
 252 TRUE if the operation was successful.
 253
 254 \membersection{wxFile::Write}\label{wxfilewrites}
 255 \func{bool}{Write}{\param{const wxString& }{s}}
 256
 257 Writes the contents of the string to the file, returns TRUE on success