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 {\bf wxFile::fd\_stdin}, {\bf wxFile::fd\_stdout} and {\bf 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.
 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, while wxFile::Eof() will return TRUE
 158 even before such attempt is made if the file pointer is at the last position
 159 in the file.
 160
 161 Note also that this function doesn't work on unseekable file descriptors
 162 (examples include pipes, terminals and sockets under Unix) and an attempt to
 163 use it will result in an error message in such case.
 164
 165 \membersection{wxFile::Exists}\label{wxfileexists}
 166
 167 \func{static bool}{Exists}{\param{const char*}{ filename}}
 168
 169 Returns TRUE if the given name specifies an existing regular file (not a
 170 directory or a link)
 171
 172 \membersection{wxFile::Flush}\label{wxfileflush}
 173
 174 \func{bool}{Flush}{\void}
 175
 176 Flushes the file descriptor.
 177
 178 Note that wxFile::Flush is not implemented on some Windows compilers
 179 due to a missing fsync function, which reduces the usefulness of this function
 180 (it can still be called but it will do nothing on unsupported compilers).
 181
 182 \membersection{wxFile::IsOpened}\label{wxfileisopened}
 183
 184 \constfunc{bool}{IsOpened}{\void}
 185
 186 Returns TRUE if the file has been opened.
 187
 188 \membersection{wxFile::Length}\label{wxfilelength}
 189
 190 \constfunc{off\_t}{Length}{\void}
 191
 192 Returns the length of the file.
 193
 194 \membersection{wxFile::Open}\label{wxfileopen}
 195
 196 \func{bool}{Open}{\param{const char*}{ filename}, \param{wxFile::OpenMode}{ mode = wxFile::read}}
 197
 198 Opens the file, returning TRUE if successful.
 199
 200 \wxheading{Parameters}
 201
 202 \docparam{filename}{The filename.}
 203
 204 \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}.}
 205
 206 \membersection{wxFile::Read}\label{wxfileread}
 207
 208 \func{off\_t}{Read}{\param{void*}{ buffer}, \param{off\_t}{ count}}
 209
 210 Reads the specified number of bytes into a buffer, returning the actual number read.
 211
 212 \wxheading{Parameters}
 213
 214 \docparam{buffer}{A buffer to receive the data.}
 215
 216 \docparam{count}{The number of bytes to read.}
 217
 218 \wxheading{Return value}
 219
 220 The number of bytes read, or the symbol {\bf wxInvalidOffset} (-1) if there was an error.
 221
 222 \membersection{wxFile::Seek}\label{wxfileseek}
 223
 224 \func{off\_t}{Seek}{\param{off\_t }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
 225
 226 Seeks to the specified position.
 227
 228 \wxheading{Parameters}
 229
 230 \docparam{ofs}{Offset to seek to.}
 231
 232 \docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
 233
 234 \wxheading{Return value}
 235
 236 The actual offset position achieved, or wxInvalidOffset on failure.
 237
 238 \membersection{wxFile::SeekEnd}\label{wxfileseekend}
 239
 240 \func{off\_t}{SeekEnd}{\param{off\_t }{ofs = 0}}
 241
 242 Moves the file pointer to the specified number of bytes before the end of the file.
 243
 244 \wxheading{Parameters}
 245
 246 \docparam{ofs}{Number of bytes before the end of the file.}
 247
 248 \wxheading{Return value}
 249
 250 The actual offset position achieved, or wxInvalidOffset on failure.
 251
 252 \membersection{wxFile::Tell}\label{wxfiletell}
 253
 254 \constfunc{off\_t}{Tell}{\void}
 255
 256 Returns the current position or wxInvalidOffset if file is not opened or if another
 257 error occured.
 258
 259 \membersection{wxFile::Write}\label{wxfilewrite}
 260
 261 \func{bool}{Write}{\param{const void*}{ buffer}, \param{off\_t}{ count}}
 262
 263 Writes the specified number of bytes from a buffer.
 264
 265 \wxheading{Parameters}
 266
 267 \docparam{buffer}{A buffer containing the data.}
 268
 269 \docparam{count}{The number of bytes to write.}
 270
 271 \wxheading{Return value}
 272
 273 TRUE if the operation was successful.
 274
 275 \membersection{wxFile::Write}\label{wxfilewrites}
 276
 277 \func{bool}{Write}{\param{const wxString\& }{s}}
 278
 279 Writes the contents of the string to the file, returns TRUE on success.
 280
 281 \section{\class{wxFFile}}\label{wxffile}
 282
 283 A wxFFile performs raw file I/O. This is a very small class designed to
 284 minimize the overhead of using it - in fact, there is hardly any overhead at
 285 all, but using it brings you automatic error checking and hides differences
 286 between platforms and compilers.
 287
 288 \wxheading{Derived from}
 289
 290 None.
 291
 292 \wxheading{Include files}
 293
 294 <wx/ffile.h>
 295
 296 \twocolwidtha{7cm}
 297 \begin{twocollist}\itemsep=0pt%
 298 \twocolitem{{\bf wxFromStart}}{Count offset from the start of the file}
 299 \twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer}
 300 \twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)}
 301 \end{twocollist}
 302
 303 \latexignore{\rtfignore{\wxheading{Members}}}
 304
 305 \membersection{wxFFile::wxFFile}\label{wxffileconstr}
 306
 307 \func{}{wxFFile}{\void}
 308
 309 Default constructor.
 310
 311 \func{}{wxFFile}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
 312
 313 Opens a file with the given mode. As there is no way to return whether the
 314 operation was successful or not from the constructor you should test the
 315 return value of \helpref{IsOpened}{wxffileisopened} to check that it didn't
 316 fail.
 317
 318 \func{}{wxFFile}{\param{FILE*}{ fp}}
 319
 320 Opens a file with the given file pointer, which has already been opened.
 321
 322 \wxheading{Parameters}
 323
 324 \docparam{filename}{The filename.}
 325
 326 \docparam{mode}{The mode in which to open the file using standard C strings.}
 327
 328 \docparam{fp}{An existing file descriptor, such as stderr.}
 329
 330 \membersection{wxFFile::\destruct{wxFFile}}
 331
 332 \func{}{\destruct{wxFFile}}{\void}
 333
 334 Destructor will close the file.
 335
 336 NB: it is not virtual so you should {\it not} derive from wxFFile!
 337
 338 \membersection{wxFFile::Attach}\label{wxffileattach}
 339
 340 \func{void}{Attach}{\param{FILE*}{ fp}}
 341
 342 Attaches an existing file pointer to the wxFFile object.
 343
 344 The descriptor should be already opened and it will be closed by wxFFile
 345 object.
 346
 347 \membersection{wxFFile::Close}\label{wxffileclose}
 348
 349 \func{bool}{Close}{\void}
 350
 351 Closes the file and returns TRUE on success.
 352
 353 \membersection{wxFFile::Detach}\label{wxffiledetach}
 354
 355 \func{void}{Detach}{\void}
 356
 357 Get back a file pointer from wxFFile object - the caller is responsible for closing the file if this
 358 descriptor is opened. \helpref{IsOpened()}{wxffileisopened} will return FALSE after call to Detach().
 359
 360 \membersection{wxFFile::fp}\label{wxffilefp}
 361
 362 \constfunc{FILE *}{fp}{\void}
 363
 364 Returns the file pointer associated with the file.
 365
 366 \membersection{wxFFile::Eof}\label{wxffileeof}
 367
 368 \constfunc{bool}{Eof}{\void}
 369
 370 Returns TRUE if the an attempt has been made to read {\it past}
 371 the end of the file.
 372
 373 Note that the behaviour of the file descriptor based class
 374 \helpref{wxFile}{wxfile} is different as \helpref{wxFile::Eof}{wxfileeof}
 375 will return TRUE here as soon as the last byte of the file has been
 376 read.
 377
 378 \membersection{wxFFile::Flush}\label{wxffileflush}
 379
 380 \func{bool}{Flush}{\void}
 381
 382 Flushes the file and returns TRUE on success.
 383
 384 \membersection{wxFFile::IsOpened}\label{wxffileisopened}
 385
 386 \constfunc{bool}{IsOpened}{\void}
 387
 388 Returns TRUE if the file has been opened.
 389
 390 \membersection{wxFFile::Length}\label{wxffilelength}
 391
 392 \constfunc{size\_t}{Length}{\void}
 393
 394 Returns the length of the file.
 395
 396 \membersection{wxFFile::Open}\label{wxffileopen}
 397
 398 \func{bool}{Open}{\param{const char*}{ filename}, \param{const char*}{ mode = "r"}}
 399
 400 Opens the file, returning TRUE if successful.
 401
 402 \wxheading{Parameters}
 403
 404 \docparam{filename}{The filename.}
 405
 406 \docparam{mode}{The mode in which to open the file.}
 407
 408 \membersection{wxFFile::Read}\label{wxffileread}
 409
 410 \func{size\_t}{Read}{\param{void*}{ buffer}, \param{off\_t}{ count}}
 411
 412 Reads the specified number of bytes into a buffer, returning the actual number read.
 413
 414 \wxheading{Parameters}
 415
 416 \docparam{buffer}{A buffer to receive the data.}
 417
 418 \docparam{count}{The number of bytes to read.}
 419
 420 \wxheading{Return value}
 421
 422 The number of bytes read.
 423
 424 \membersection{wxFFile::Seek}\label{wxffileseek}
 425
 426 \func{bool}{Seek}{\param{long }{ofs}, \param{wxSeekMode }{mode = wxFromStart}}
 427
 428 Seeks to the specified position and returs TRUE on success.
 429
 430 \wxheading{Parameters}
 431
 432 \docparam{ofs}{Offset to seek to.}
 433
 434 \docparam{mode}{One of {\bf wxFromStart}, {\bf wxFromEnd}, {\bf wxFromCurrent}.}
 435
 436 \membersection{wxFFile::SeekEnd}\label{wxffileseekend}
 437
 438 \func{bool}{SeekEnd}{\param{long }{ofs = 0}}
 439
 440 Moves the file pointer to the specified number of bytes before the end of the file
 441 and returns TRUE on success.
 442
 443 \wxheading{Parameters}
 444
 445 \docparam{ofs}{Number of bytes before the end of the file.}
 446
 447 \membersection{wxFFile::Tell}\label{wxffiletell}
 448
 449 \constfunc{size\_t}{Tell}{\void}
 450
 451 Returns the current position.
 452
 453 \membersection{wxFFile::Write}\label{wxffilewrite}
 454
 455 \func{size\_t}{Write}{\param{const void*}{ buffer}, \param{size\_t}{ count}}
 456
 457 Writes the specified number of bytes from a buffer.
 458
 459 \wxheading{Parameters}
 460
 461 \docparam{buffer}{A buffer containing the data.}
 462
 463 \docparam{count}{The number of bytes to write.}
 464
 465 \wxheading{Return value}
 466
 467 Number of bytes written.
 468
 469 \membersection{wxFFile::Write}\label{wxffilewrites}
 470
 471 \func{bool}{Write}{\param{const wxString\& }{s}}
 472
 473 Writes the contents of the string to the file, returns TRUE on success.
 474