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. wxFile also automatically closes the file in
   7 its destructor making it unnecessary to worry about forgetting to do it.
   8
   9 \wxheading{Derived from}
  10
  11 None.
  12
  13 \wxheading{Include files}
  14
  15 <wx/file.h>
  16
  17 \wxheading{Constants}
  18
  19 wx/file.h defines the following constants:
  20
  21 {\small
  22 \begin{verbatim}
  23 #define wxS_IRUSR 00400
  24 #define wxS_IWUSR 00200
  25 #define wxS_IXUSR 00100
  26
  27 #define wxS_IRGRP 00040
  28 #define wxS_IWGRP 00020
  29 #define wxS_IXGRP 00010
  30
  31 #define wxS_IROTH 00004
  32 #define wxS_IWOTH 00002
  33 #define wxS_IXOTH 00001
  34
  35 // default mode for the new files: corresponds to umask 022
  36 #define wxS_DEFAULT  (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH)
  37 \end{verbatim}
  38 }
  39
  40 These constants define the file access rights and are used with
  41 \helpref{wxFile::Create}{wxfilecreate} and \helpref{wxFile::Open}{wxfileopen}.
  42
  43 The {\it OpenMode} enumeration defines the different modes for opening a file,
  44 it's defined inside wxFile class so its members should be specified with {\it wxFile::} scope
  45 resolution prefix. It is also used with \helpref{wxFile::Access}{wxfileaccess} function.
  46
  47 \twocolwidtha{7cm}
  48 \begin{twocollist}\itemsep=0pt%
  49 \twocolitem{{\bf wxFile::read}}{Open file for reading or test if it can be opened for reading with Access()}
  50 \twocolitem{{\bf wxFile::write}}{Open file for writing deleting the contents of the file if it already exists
  51 or test if it can be opened for writing with Access()}
  52 \twocolitem{{\bf wxFile::read\_write}}{Open file for reading and writing; can not be used with Access()}
  53 \twocolitem{{\bf wxFile::write\_append}}{Open file for appending: the file is opened for writing, but the old
  54 contents of the file is not erased and the file pointer is initially placed at the end of the file;
  55 can not be used with Access()}
  56 \end{twocollist}
  57
  58 Other constants defined elsewhere but used by wxFile functions are wxInvalidOffset which represents an
  59 invalid value of type {\it off\_t} and is returned by functions returning {\it off\_t} on error and the seek
  60 mode constants used with \helpref{Seek()}{wxfileseek}:
  61
  62 \twocolwidtha{7cm}
  63 \begin{twocollist}\itemsep=0pt%
  64 \twocolitem{{\bf wxFromStart}}{Count offset from the start of the file}
  65 \twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer}
  66 \twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)}
  67 \end{twocollist}
  68
  69 \latexignore{\rtfignore{\wxheading{Members}}}
  70
  71 \membersection{wxFile::wxFile}\label{wxfileconstr}
  72
  73 \func{}{wxFile}{\void}
  74
  75 Default constructor.
  76
  77 \func{}{wxFile}{\param{const char*}{ filename}, \param{wxFile::OpenMode}{ mode = wxFile::read}}
  78
  79 Opens a file with the given mode. As there is no way to return whether the
  80 operation was successful or not from the constructor you should test the
  81 return value of \helpref{IsOpened}{wxfileisopened} to check that it didn't
  82 fail.
  83
  84 \func{}{wxFile}{\param{int}{ fd}}
  85
  86 Associates the file with the given file descriptor, which has already been opened.
  87
  88 \wxheading{Parameters}
  89
  90 \docparam{filename}{The filename.}
  91
  92 \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}.}
  93
  94 \docparam{fd}{An existing file descriptor (see \helpref{Attach()}{wxfileattach} for the list of predefined descriptors)}
  95
  96 \membersection{wxFile::\destruct{wxFile}}
  97
  98 \func{}{\destruct{wxFile}}{\void}
  99
 100 Destructor will close the file.
 101
 102 NB: it is not virtual so you should use wxFile polymorphically.
 103
 104 \membersection{wxFile::Access}\label{wxfileaccess}
 105
 106 \func{static bool}{Access}{\param{const char *}{ name}, \param{OpenMode}{ mode}}
 107
 108 This function verifies if we may access the given file in specified mode. Only
 109 values of wxFile::read or wxFile::write really make sense here.
 110
 111 \membersection{wxFile::Attach}\label{wxfileattach}
 112
 113 \func{void}{Attach}{\param{int}{ fd}}
 114
 115 Attaches an existing file descriptor to the wxFile object. Example of predefined
 116 file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr (and
 117 have symbolic names of wxFile::fd\_stdin, wxFile::fd\_stdout and wxFile::fd\_stderr).
 118
 119 The descriptor should be already opened and it will be closed by wxFile
 120 object.
 121
 122 \membersection{wxFile::Close}\label{wxfileclose}
 123
 124 \func{void}{Close}{\void}
 125
 126 Closes the file.
 127
 128 \membersection{wxFile::Create}\label{wxfilecreate}
 129
 130 \func{bool}{Create}{\param{const char*}{ filename}, \param{bool}{ overwrite = FALSE}, \param{int }{access = wxS\_DEFAULT}}
 131
 132 Creates a file for writing. If the file already exists, setting {\bf overwrite} to TRUE
 133 will ensure it is overwritten.
 134
 135 \membersection{wxFile::Detach}\label{wxfiledetach}
 136
 137 \func{void}{Detach}{\void}
 138
 139 Get back a file descriptor from wxFile object - the caller is responsible for closing the file if this
 140 descriptor is opened. \helpref{IsOpened()}{wxfileisopened} will return FALSE after call to Detach().
 141
 142 \membersection{wxFile::fd}\label{wxfilefd}
 143
 144 \constfunc{int}{fd}{\void}
 145
 146 Returns the file descriptor associated with the file.
 147
 148 \membersection{wxFile::Eof}\label{wxfileeof}
 149
 150 \constfunc{bool}{Eof}{\void}
 151
 152 Returns TRUE if the end of the file has been reached (the last byte has been read).
 153
 154 Note that the behaviour of the file pointer based class
 155 \helpref{wxFFile}{wxffile} is different as \helpref{wxFFile::Eof}{wxffileeof}
 156 will return TRUE here only if an attempt has been made to read
 157 {\it past} the last byte of the file.
 158
 159 \membersection{wxFile::Exists}\label{wxfileexists}
 160
 161 \func{static bool}{Exists}{\param{const char*}{ filename}}
 162
 163 Returns TRUE if the given name specifies an existing regular file (not a
 164 directory or a link)
 165
 166 \membersection{wxFile::Flush}\label{wxfileflush}
 167
 168 \func{bool}{Flush}{\void}
 169
 170 Flushes the file descriptor.
 171
 172 Note that wxFile::Flush is not implemented on some Windows compilers
 173 due to a missing fsync function, which reduces the usefulness of this function
 174 (it can still be called but it will do nothing on unsupported compilers).
 175
 176 \membersection{wxFile::IsOpened}\label{wxfileisopened}
 177
 178 \constfunc{bool}{IsOpened}{\void}
 179
 180 Returns TRUE if the file has been opened.
 181
 182 \membersection{wxFile::Length}\label{wxfilelength}
 183
 184 \constfunc{off\_t}{Length}{\void}
 185
 186 Returns the length of the file.
 187
 188 \membersection{wxFile::Open}\label{wxfileopen}
 189
 190 \func{bool}{Open}{\param{const char*}{ filename}, \param{wxFile::OpenMode}{ mode = wxFile::read}}
 191
 192 Opens the file, returning TRUE if successful.
 193
 194 \wxheading{Parameters}
 195
 196 \docparam{filename}{The filename.}
 197
 198 \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}.}
 199
 200 \membersection{wxFile::Read}\label{wxfileread}
 201
 202 \func{off\_t}{Read}{\param{void*}{ buffer}, \param{off\_t}{ count}}
 203
 204 Reads the specified number of bytes into a buffer, returning the actual number read.
 205
 206 \wxheading{Parameters}
 207
 208 \docparam{buffer}{A buffer to receive the data.}
 209
 210 \docparam{count}{The number of bytes to read.}
 211
 212 \wxheading{Return value}
 213
 214 The number of bytes read, or the symbol {\bf wxInvalidOffset} (-1) if there was an error.
 215
 216 \membersection{wxFile::Seek}\label{wxfileseek}
 217
 218 \func{off\_t}{Seek}{\param{off\_t }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
 219
 220 Seeks to the specified position.
 221
 222 \wxheading{Parameters}
 223
 224 \docparam{ofs}{Offset to seek to.}
 225
 226 \docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
 227
 228 \wxheading{Return value}
 229
 230 The actual offset position achieved, or wxInvalidOffset on failure.
 231
 232 \membersection{wxFile::SeekEnd}\label{wxfileseekend}
 233
 234 \func{off\_t}{SeekEnd}{\param{off\_t }{ofs = 0}}
 235
 236 Moves the file pointer to the specified number of bytes before the end of the file.
 237
 238 \wxheading{Parameters}
 239
 240 \docparam{ofs}{Number of bytes before the end of the file.}
 241
 242 \wxheading{Return value}
 243
 244 The actual offset position achieved, or wxInvalidOffset on failure.
 245
 246 \membersection{wxFile::Tell}\label{wxfiletell}
 247
 248 \constfunc{off\_t}{Tell}{\void}
 249
 250 Returns the current position or wxInvalidOffset if file is not opened or if another
 251 error occured.
 252
 253 \membersection{wxFile::Write}\label{wxfilewrite}
 254
 255 \func{bool}{Write}{\param{const void*}{ buffer}, \param{off\_t}{ count}}
 256
 257 Writes the specified number of bytes from a buffer.
 258
 259 \wxheading{Parameters}
 260
 261 \docparam{buffer}{A buffer containing the data.}
 262
 263 \docparam{count}{The number of bytes to write.}
 264
 265 \wxheading{Return value}
 266
 267 TRUE if the operation was successful.
 268
 269 \membersection{wxFile::Write}\label{wxfilewrites}
 270
 271 \func{bool}{Write}{\param{const wxString\& }{s}}
 272
 273 Writes the contents of the string to the file, returns TRUE on success.
 274
 275 \section{\class{wxFFile}}\label{wxffile}
 276
 277 A wxFFile performs raw file I/O. This is a very small class designed to
 278 minimize the overhead of using it - in fact, there is hardly any overhead at
 279 all, but using it brings you automatic error checking and hides differences
 280 between platforms and compilers.
 281
 282 \wxheading{Derived from}
 283
 284 None.
 285
 286 \wxheading{Include files}
 287
 288 <wx/ffile.h>
 289
 290 \twocolwidtha{7cm}
 291 \begin{twocollist}\itemsep=0pt%
 292 \twocolitem{{\bf wxFromStart}}{Count offset from the start of the file}
 293 \twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer}
 294 \twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)}
 295 \end{twocollist}
 296
 297 \latexignore{\rtfignore{\wxheading{Members}}}
 298
 299 \membersection{wxFFile::wxFFile}\label{wxffileconstr}
 300
 301 \func{}{wxFFile}{\void}
 302
 303 Default constructor.
 304
 305 \func{}{wxFFile}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
 306
 307 Opens a file with the given mode. As there is no way to return whether the
 308 operation was successful or not from the constructor you should test the
 309 return value of \helpref{IsOpened}{wxffileisopened} to check that it didn't
 310 fail.
 311
 312 \func{}{wxFFile}{\param{FILE*}{ fp}}
 313
 314 Opens a file with the given file pointer, which has already been opened.
 315
 316 \wxheading{Parameters}
 317
 318 \docparam{filename}{The filename.}
 319
 320 \docparam{mode}{The mode in which to open the file using standard C strings.}
 321
 322 \docparam{fp}{An existing file descriptor, such as stderr.}
 323
 324 \membersection{wxFFile::\destruct{wxFFile}}
 325
 326 \func{}{\destruct{wxFFile}}{\void}
 327
 328 Destructor will close the file.
 329
 330 NB: it is not virtual so you should {\it not} derive from wxFFile!
 331
 332 \membersection{wxFFile::Attach}\label{wxffileattach}
 333
 334 \func{void}{Attach}{\param{FILE*}{ fp}}
 335
 336 Attaches an existing file pointer to the wxFFile object.
 337
 338 The descriptor should be already opened and it will be closed by wxFFile
 339 object.
 340
 341 \membersection{wxFFile::Close}\label{wxffileclose}
 342
 343 \func{bool}{Close}{\void}
 344
 345 Closes the file and returns TRUE on success.
 346
 347 \membersection{wxFFile::Detach}\label{wxffiledetach}
 348
 349 \func{void}{Detach}{\void}
 350
 351 Get back a file pointer from wxFFile object - the caller is responsible for closing the file if this
 352 descriptor is opened. \helpref{IsOpened()}{wxffileisopened} will return FALSE after call to Detach().
 353
 354 \membersection{wxFFile::fp}\label{wxffilefp}
 355
 356 \constfunc{FILE *}{fp}{\void}
 357
 358 Returns the file pointer associated with the file.
 359
 360 \membersection{wxFFile::Eof}\label{wxffileeof}
 361
 362 \constfunc{bool}{Eof}{\void}
 363
 364 Returns TRUE if the an attempt has been made to read {\it past}
 365 the end of the file.
 366
 367 Note that the behaviour of the file descriptor based class
 368 \helpref{wxFile}{wxfile} is different as \helpref{wxFile::Eof}{wxfileeof}
 369 will return TRUE here as soon as the last byte of the file has been
 370 read.
 371
 372 \membersection{wxFFile::Flush}\label{wxffileflush}
 373
 374 \func{bool}{Flush}{\void}
 375
 376 Flushes the file and returns TRUE on success.
 377
 378 \membersection{wxFFile::IsOpened}\label{wxffileisopened}
 379
 380 \constfunc{bool}{IsOpened}{\void}
 381
 382 Returns TRUE if the file has been opened.
 383
 384 \membersection{wxFFile::Length}\label{wxffilelength}
 385
 386 \constfunc{size\_t}{Length}{\void}
 387
 388 Returns the length of the file.
 389
 390 \membersection{wxFFile::Open}\label{wxffileopen}
 391
 392 \func{bool}{Open}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
 393
 394 Opens the file, returning TRUE if successful.
 395
 396 \wxheading{Parameters}
 397
 398 \docparam{filename}{The filename.}
 399
 400 \docparam{mode}{The mode in which to open the file.}
 401
 402 \membersection{wxFFile::Read}\label{wxffileread}
 403
 404 \func{size\_t}{Read}{\param{void*}{ buffer}, \param{off\_t}{ count}}
 405
 406 Reads the specified number of bytes into a buffer, returning the actual number read.
 407
 408 \wxheading{Parameters}
 409
 410 \docparam{buffer}{A buffer to receive the data.}
 411
 412 \docparam{count}{The number of bytes to read.}
 413
 414 \wxheading{Return value}
 415
 416 The number of bytes read.
 417
 418 \membersection{wxFFile::Seek}\label{wxffileseek}
 419
 420 \func{bool}{Seek}{\param{long }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
 421
 422 Seeks to the specified position and returs TRUE on success.
 423
 424 \wxheading{Parameters}
 425
 426 \docparam{ofs}{Offset to seek to.}
 427
 428 \docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
 429
 430 \membersection{wxFFile::SeekEnd}\label{wxffileseekend}
 431
 432 \func{bool}{SeekEnd}{\param{long }{ofs = 0}}
 433
 434 Moves the file pointer to the specified number of bytes before the end of the file
 435 and returns TRUE on success.
 436
 437 \wxheading{Parameters}
 438
 439 \docparam{ofs}{Number of bytes before the end of the file.}
 440
 441 \membersection{wxFFile::Tell}\label{wxffiletell}
 442
 443 \constfunc{size\_t}{Tell}{\void}
 444
 445 Returns the current position.
 446
 447 \membersection{wxFFile::Write}\label{wxffilewrite}
 448
 449 \func{size_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}}
 450
 451 Writes the specified number of bytes from a buffer.
 452
 453 \wxheading{Parameters}
 454
 455 \docparam{buffer}{A buffer containing the data.}
 456
 457 \docparam{count}{The number of bytes to write.}
 458
 459 \wxheading{Return value}
 460
 461 Number of bytes written.
 462
 463 \membersection{wxFFile::Write}\label{wxffilewrites}
 464
 465 \func{bool}{Write}{\param{const wxString\& }{s}}
 466
 467 Writes the contents of the string to the file, returns TRUE on success.
 468