| 1 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 2 | %% Name: file.tex |
| 3 | %% Purpose: wxFile documentation |
| 4 | %% Author: Vadim Zeitlin |
| 5 | %% Modified by: |
| 6 | %% Created: 14.01.02 (extracted from file.tex) |
| 7 | %% RCS-ID: $Id$ |
| 8 | %% Copyright: (c) Vadim Zeitlin |
| 9 | %% License: wxWindows license |
| 10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 11 | |
| 12 | \section{\class{wxFile}}\label{wxfile} |
| 13 | |
| 14 | A wxFile performs raw file I/O. This is a very small class designed to |
| 15 | minimize the overhead of using it - in fact, there is hardly any overhead at |
| 16 | all, but using it brings you automatic error checking and hides differences |
| 17 | between platforms and compilers. wxFile also automatically closes the file in |
| 18 | its destructor making it unnecessary to worry about forgetting to do it. |
| 19 | wxFile is a wrapper around {\tt file descriptor.} - see also |
| 20 | \helpref{wxFFile}{wxffile} for a wrapper around {\tt FILE} structure. |
| 21 | |
| 22 | {\tt wxFileOffset} is used by the wxFile functions which require offsets as |
| 23 | parameter or return them. If the platform supports it, wxFileOffset if a typedef |
| 24 | for a native 64 bit integer, else a 32 bit integer is used for wxFileOffset. |
| 25 | |
| 26 | \wxheading{Derived from} |
| 27 | |
| 28 | None. |
| 29 | |
| 30 | \wxheading{Include files} |
| 31 | |
| 32 | <wx/file.h> |
| 33 | |
| 34 | \wxheading{Constants} |
| 35 | |
| 36 | wx/file.h defines the following constants: |
| 37 | |
| 38 | \begin{verbatim} |
| 39 | #define wxS_IRUSR 00400 |
| 40 | #define wxS_IWUSR 00200 |
| 41 | #define wxS_IXUSR 00100 |
| 42 | |
| 43 | #define wxS_IRGRP 00040 |
| 44 | #define wxS_IWGRP 00020 |
| 45 | #define wxS_IXGRP 00010 |
| 46 | |
| 47 | #define wxS_IROTH 00004 |
| 48 | #define wxS_IWOTH 00002 |
| 49 | #define wxS_IXOTH 00001 |
| 50 | |
| 51 | // default mode for the new files: corresponds to umask 022 |
| 52 | #define wxS_DEFAULT (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH) |
| 53 | \end{verbatim} |
| 54 | |
| 55 | These constants define the file access rights and are used with |
| 56 | \helpref{wxFile::Create}{wxfilecreate} and \helpref{wxFile::Open}{wxfileopen}. |
| 57 | |
| 58 | The {\it OpenMode} enumeration defines the different modes for opening a file, |
| 59 | it is defined inside wxFile class so its members should be specified with {\it wxFile::} scope |
| 60 | resolution prefix. It is also used with \helpref{wxFile::Access}{wxfileaccess} function. |
| 61 | |
| 62 | \twocolwidtha{7cm} |
| 63 | \begin{twocollist}\itemsep=0pt% |
| 64 | \twocolitem{{\bf wxFile::read}}{Open file for reading or test if it can be opened for reading with Access()} |
| 65 | \twocolitem{{\bf wxFile::write}}{Open file for writing deleting the contents of the file if it already exists |
| 66 | or test if it can be opened for writing with Access()} |
| 67 | \twocolitem{{\bf wxFile::read\_write}}{Open file for reading and writing; can not be used with Access()} |
| 68 | \twocolitem{{\bf wxFile::write\_append}}{Open file for appending: the file is opened for writing, but the old |
| 69 | contents of the file is not erased and the file pointer is initially placed at the end of the file; |
| 70 | can not be used with Access(). This is the same as {\bf wxFile::write} if the |
| 71 | file doesn't exist.} |
| 72 | \twocolitem{{\bf wxFile::write\_excl}}{Open the file securely for writing (Uses O\_EXCL | O\_CREAT). |
| 73 | Will fail if the file already exists, else create and open it atomically. Useful for opening temporary files without being vulnerable to race exploits.} |
| 74 | \end{twocollist} |
| 75 | |
| 76 | Other constants defined elsewhere but used by wxFile functions are wxInvalidOffset which represents an |
| 77 | invalid value of type {\it wxFileOffset} and is returned by functions returning {\it wxFileOffset} on error and the seek |
| 78 | mode constants used with \helpref{Seek()}{wxfileseek}: |
| 79 | |
| 80 | \twocolwidtha{7cm} |
| 81 | \begin{twocollist}\itemsep=0pt% |
| 82 | \twocolitem{{\bf wxFromStart}}{Count offset from the start of the file} |
| 83 | \twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer} |
| 84 | \twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)} |
| 85 | \end{twocollist} |
| 86 | |
| 87 | \latexignore{\rtfignore{\wxheading{Members}}} |
| 88 | |
| 89 | |
| 90 | \membersection{wxFile::wxFile}\label{wxfilector} |
| 91 | |
| 92 | \func{}{wxFile}{\void} |
| 93 | |
| 94 | Default constructor. |
| 95 | |
| 96 | \func{}{wxFile}{\param{const char*}{ filename}, \param{wxFile::OpenMode}{ mode = wxFile::read}} |
| 97 | |
| 98 | Opens a file with the given mode. As there is no way to return whether the |
| 99 | operation was successful or not from the constructor you should test the |
| 100 | return value of \helpref{IsOpened}{wxfileisopened} to check that it didn't |
| 101 | fail. |
| 102 | |
| 103 | \func{}{wxFile}{\param{int}{ fd}} |
| 104 | |
| 105 | Associates the file with the given file descriptor, which has already been opened. |
| 106 | |
| 107 | \wxheading{Parameters} |
| 108 | |
| 109 | \docparam{filename}{The filename.} |
| 110 | |
| 111 | \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}.} |
| 112 | |
| 113 | \docparam{fd}{An existing file descriptor (see \helpref{Attach()}{wxfileattach} for the list of predefined descriptors)} |
| 114 | |
| 115 | |
| 116 | \membersection{wxFile::\destruct{wxFile}}\label{wxfiledtor} |
| 117 | |
| 118 | \func{}{\destruct{wxFile}}{\void} |
| 119 | |
| 120 | Destructor will close the file. |
| 121 | |
| 122 | {\bf NB:} it is not virtual so you should not use wxFile polymorphically. |
| 123 | |
| 124 | |
| 125 | \membersection{wxFile::Access}\label{wxfileaccess} |
| 126 | |
| 127 | \func{static bool}{Access}{\param{const char *}{ name}, \param{OpenMode}{ mode}} |
| 128 | |
| 129 | This function verifies if we may access the given file in specified mode. Only |
| 130 | values of wxFile::read or wxFile::write really make sense here. |
| 131 | |
| 132 | |
| 133 | \membersection{wxFile::Attach}\label{wxfileattach} |
| 134 | |
| 135 | \func{void}{Attach}{\param{int}{ fd}} |
| 136 | |
| 137 | Attaches an existing file descriptor to the wxFile object. Example of predefined |
| 138 | file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr (and |
| 139 | have symbolic names of {\bf wxFile::fd\_stdin}, {\bf wxFile::fd\_stdout} and {\bf wxFile::fd\_stderr}). |
| 140 | |
| 141 | The descriptor should be already opened and it will be closed by wxFile |
| 142 | object. |
| 143 | |
| 144 | |
| 145 | \membersection{wxFile::Close}\label{wxfileclose} |
| 146 | |
| 147 | \func{void}{Close}{\void} |
| 148 | |
| 149 | Closes the file. |
| 150 | |
| 151 | |
| 152 | \membersection{wxFile::Create}\label{wxfilecreate} |
| 153 | |
| 154 | \func{bool}{Create}{\param{const char*}{ filename}, \param{bool}{ overwrite = false}, \param{int }{access = wxS\_DEFAULT}} |
| 155 | |
| 156 | Creates a file for writing. If the file already exists, setting {\bf overwrite} to true |
| 157 | will ensure it is overwritten. |
| 158 | |
| 159 | |
| 160 | \membersection{wxFile::Detach}\label{wxfiledetach} |
| 161 | |
| 162 | \func{void}{Detach}{\void} |
| 163 | |
| 164 | Get back a file descriptor from wxFile object - the caller is responsible for closing the file if this |
| 165 | descriptor is opened. \helpref{IsOpened()}{wxfileisopened} will return false after call to Detach(). |
| 166 | |
| 167 | |
| 168 | \membersection{wxFile::fd}\label{wxfilefd} |
| 169 | |
| 170 | \constfunc{int}{fd}{\void} |
| 171 | |
| 172 | Returns the file descriptor associated with the file. |
| 173 | |
| 174 | |
| 175 | \membersection{wxFile::Eof}\label{wxfileeof} |
| 176 | |
| 177 | \constfunc{bool}{Eof}{\void} |
| 178 | |
| 179 | Returns true if the end of the file has been reached. |
| 180 | |
| 181 | Note that the behaviour of the file pointer based class |
| 182 | \helpref{wxFFile}{wxffile} is different as \helpref{wxFFile::Eof}{wxffileeof} |
| 183 | will return true here only if an attempt has been made to read |
| 184 | {\it past} the last byte of the file, while wxFile::Eof() will return true |
| 185 | even before such attempt is made if the file pointer is at the last position |
| 186 | in the file. |
| 187 | |
| 188 | Note also that this function doesn't work on unseekable file descriptors |
| 189 | (examples include pipes, terminals and sockets under Unix) and an attempt to |
| 190 | use it will result in an error message in such case. So, to read the entire |
| 191 | file into memory, you should write a loop which uses |
| 192 | \helpref{Read}{wxfileread} repeatedly and tests its return condition instead |
| 193 | of using Eof() as this will not work for special files under Unix. |
| 194 | |
| 195 | |
| 196 | \membersection{wxFile::Exists}\label{wxfileexists} |
| 197 | |
| 198 | \func{static bool}{Exists}{\param{const char*}{ filename}} |
| 199 | |
| 200 | Returns true if the given name specifies an existing regular file (not a |
| 201 | directory or a link) |
| 202 | |
| 203 | |
| 204 | \membersection{wxFile::Flush}\label{wxfileflush} |
| 205 | |
| 206 | \func{bool}{Flush}{\void} |
| 207 | |
| 208 | Flushes the file descriptor. |
| 209 | |
| 210 | Note that wxFile::Flush is not implemented on some Windows compilers |
| 211 | due to a missing fsync function, which reduces the usefulness of this function |
| 212 | (it can still be called but it will do nothing on unsupported compilers). |
| 213 | |
| 214 | |
| 215 | \membersection{wxFile::GetKind}\label{wxfilegetfilekind} |
| 216 | |
| 217 | \constfunc{wxFileKind}{GetKind}{\void} |
| 218 | |
| 219 | Returns the type of the file. Possible return values are: |
| 220 | |
| 221 | \begin{verbatim} |
| 222 | enum wxFileKind |
| 223 | { |
| 224 | wxFILE_KIND_UNKNOWN, |
| 225 | wxFILE_KIND_DISK, // a file supporting seeking to arbitrary offsets |
| 226 | wxFILE_KIND_TERMINAL, // a tty |
| 227 | wxFILE_KIND_PIPE // a pipe |
| 228 | }; |
| 229 | |
| 230 | \end{verbatim} |
| 231 | |
| 232 | |
| 233 | \membersection{wxFile::IsOpened}\label{wxfileisopened} |
| 234 | |
| 235 | \constfunc{bool}{IsOpened}{\void} |
| 236 | |
| 237 | Returns true if the file has been opened. |
| 238 | |
| 239 | |
| 240 | \membersection{wxFile::Length}\label{wxfilelength} |
| 241 | |
| 242 | \constfunc{wxFileOffset}{Length}{\void} |
| 243 | |
| 244 | Returns the length of the file. |
| 245 | |
| 246 | |
| 247 | \membersection{wxFile::Open}\label{wxfileopen} |
| 248 | |
| 249 | \func{bool}{Open}{\param{const char*}{ filename}, \param{wxFile::OpenMode}{ mode = wxFile::read}} |
| 250 | |
| 251 | Opens the file, returning true if successful. |
| 252 | |
| 253 | \wxheading{Parameters} |
| 254 | |
| 255 | \docparam{filename}{The filename.} |
| 256 | |
| 257 | \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}.} |
| 258 | |
| 259 | |
| 260 | \membersection{wxFile::Read}\label{wxfileread} |
| 261 | |
| 262 | \func{size\_t}{Read}{\param{void*}{ buffer}, \param{size\_t}{ count}} |
| 263 | |
| 264 | Reads the specified number of bytes into a buffer, returning the actual number read. |
| 265 | |
| 266 | \wxheading{Parameters} |
| 267 | |
| 268 | \docparam{buffer}{A buffer to receive the data.} |
| 269 | |
| 270 | \docparam{count}{The number of bytes to read.} |
| 271 | |
| 272 | \wxheading{Return value} |
| 273 | |
| 274 | The number of bytes read, or the symbol {\bf wxInvalidOffset} (-1) if there was an error. |
| 275 | |
| 276 | |
| 277 | \membersection{wxFile::Seek}\label{wxfileseek} |
| 278 | |
| 279 | \func{wxFileOffset}{Seek}{\param{wxFileOffset }{ofs}, \param{wxSeekMode }{mode = wxFromStart}} |
| 280 | |
| 281 | Seeks to the specified position. |
| 282 | |
| 283 | \wxheading{Parameters} |
| 284 | |
| 285 | \docparam{ofs}{Offset to seek to.} |
| 286 | |
| 287 | \docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.} |
| 288 | |
| 289 | \wxheading{Return value} |
| 290 | |
| 291 | The actual offset position achieved, or wxInvalidOffset on failure. |
| 292 | |
| 293 | |
| 294 | \membersection{wxFile::SeekEnd}\label{wxfileseekend} |
| 295 | |
| 296 | \func{wxFileOffset}{SeekEnd}{\param{wxFileOffset }{ofs = 0}} |
| 297 | |
| 298 | Moves the file pointer to the specified number of bytes relative to the end of |
| 299 | the file. For example, \texttt{SeekEnd($-5$)} would position the pointer $5$ |
| 300 | bytes before the end. |
| 301 | |
| 302 | \wxheading{Parameters} |
| 303 | |
| 304 | \docparam{ofs}{Number of bytes before the end of the file.} |
| 305 | |
| 306 | \wxheading{Return value} |
| 307 | |
| 308 | The actual offset position achieved, or wxInvalidOffset on failure. |
| 309 | |
| 310 | |
| 311 | \membersection{wxFile::Tell}\label{wxfiletell} |
| 312 | |
| 313 | \constfunc{wxFileOffset}{Tell}{\void} |
| 314 | |
| 315 | Returns the current position or wxInvalidOffset if file is not opened or if another |
| 316 | error occurred. |
| 317 | |
| 318 | |
| 319 | \membersection{wxFile::Write}\label{wxfilewrite} |
| 320 | |
| 321 | \func{size\_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}} |
| 322 | |
| 323 | Writes the specified number of bytes from a buffer. |
| 324 | |
| 325 | \wxheading{Parameters} |
| 326 | |
| 327 | \docparam{buffer}{A buffer containing the data.} |
| 328 | |
| 329 | \docparam{count}{The number of bytes to write.} |
| 330 | |
| 331 | \wxheading{Return value} |
| 332 | |
| 333 | the number of bytes actually written |
| 334 | |
| 335 | |
| 336 | \membersection{wxFile::Write}\label{wxfilewrites} |
| 337 | |
| 338 | \func{bool}{Write}{\param{const wxString\& }{s}, \param{wxMBConv\&}{ conv = wxConvUTF8}} |
| 339 | |
| 340 | Writes the contents of the string to the file, returns true on success. |
| 341 | |
| 342 | The second argument is only meaningful in Unicode build of wxWidgets when |
| 343 | {\it conv} is used to convert {\it s} to multibyte representation. |
| 344 | |
| 345 | Note that this method only works with {\tt NUL}-terminated strings, if you want |
| 346 | to write data with embedded {\tt NUL}s to the file you should use the other |
| 347 | \helpref{Write() overload}{wxfilewrite}. |
| 348 | |