1 \section{\class{wxFile
}}\label{wxfile
}
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.
9 \wxheading{Derived from
}
13 \wxheading{Include files
}
19 wx/file.h defines the following constants:
23 #define wxS_IRUSR
00400
24 #define wxS_IWUSR
00200
25 #define wxS_IXUSR
00100
27 #define wxS_IRGRP
00040
28 #define wxS_IWGRP
00020
29 #define wxS_IXGRP
00010
31 #define wxS_IROTH
00004
32 #define wxS_IWOTH
00002
33 #define wxS_IXOTH
00001
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)
40 These constants define the file access rights and are used with
41 \helpref{wxFile::Create
}{wxfilecreate
} and
\helpref{wxFile::Open
}{wxfileopen
}.
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.
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()
}
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
}:
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)
}
69 \latexignore{\rtfignore{\wxheading{Members
}}}
71 \membersection{wxFile::wxFile
}\label{wxfileconstr
}
73 \func{}{wxFile
}{\void}
77 \func{}{wxFile
}{\param{const char*
}{ filename
},
\param{wxFile::OpenMode
}{ mode = wxFile::read
}}
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
84 \func{}{wxFile
}{\param{int
}{ fd
}}
86 Associates the file with the given file descriptor, which has already been opened.
88 \wxheading{Parameters
}
90 \docparam{filename
}{The filename.
}
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}.
}
94 \docparam{fd
}{An existing file descriptor (see
\helpref{Attach()
}{wxfileattach
} for the list of predefined descriptors)
}
96 \membersection{wxFile::
\destruct{wxFile
}}
98 \func{}{\destruct{wxFile
}}{\void}
100 Destructor will close the file.
102 NB: it is not virtual so you should use wxFile polymorphically.
104 \membersection{wxFile::Access
}\label{wxfileaccess
}
106 \func{static bool
}{Access
}{\param{const char *
}{ name
},
\param{OpenMode
}{ mode
}}
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.
111 \membersection{wxFile::Attach
}\label{wxfileattach
}
113 \func{void
}{Attach
}{\param{int
}{ fd
}}
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).
119 The descriptor should be already opened and it will be closed by wxFile
122 \membersection{wxFile::Close
}\label{wxfileclose
}
124 \func{void
}{Close
}{\void}
128 \membersection{wxFile::Create
}\label{wxfilecreate
}
130 \func{bool
}{Create
}{\param{const char*
}{ filename
},
\param{bool
}{ overwrite = FALSE
},
\param{int
}{access = wxS
\_DEFAULT}}
132 Creates a file for writing. If the file already exists, setting
{\bf overwrite
} to TRUE
133 will ensure it is overwritten.
135 \membersection{wxFile::Detach
}\label{wxfiledetach
}
137 \func{void
}{Detach
}{\void}
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().
142 \membersection{wxFile::fd
}\label{wxfilefd
}
144 \constfunc{int
}{fd
}{\void}
146 Returns the file descriptor associated with the file.
148 \membersection{wxFile::Eof
}\label{wxfileeof
}
150 \constfunc{bool
}{Eof
}{\void}
152 Returns TRUE if the end of the file has been reached (the last byte has been read).
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.
159 \membersection{wxFile::Exists
}\label{wxfileexists
}
161 \func{static bool
}{Exists
}{\param{const char*
}{ filename
}}
163 Returns TRUE if the given name specifies an existing regular file (not a
166 \membersection{wxFile::Flush
}\label{wxfileflush
}
168 \func{bool
}{Flush
}{\void}
170 Flushes the file descriptor.
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).
176 \membersection{wxFile::IsOpened
}\label{wxfileisopened
}
178 \constfunc{bool
}{IsOpened
}{\void}
180 Returns TRUE if the file has been opened.
182 \membersection{wxFile::Length
}\label{wxfilelength
}
184 \constfunc{off
\_t}{Length
}{\void}
186 Returns the length of the file.
188 \membersection{wxFile::Open
}\label{wxfileopen
}
190 \func{bool
}{Open
}{\param{const char*
}{ filename
},
\param{wxFile::OpenMode
}{ mode = wxFile::read
}}
192 Opens the file, returning TRUE if successful.
194 \wxheading{Parameters
}
196 \docparam{filename
}{The filename.
}
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}.
}
200 \membersection{wxFile::Read
}\label{wxfileread
}
202 \func{off
\_t}{Read
}{\param{void*
}{ buffer
},
\param{off
\_t}{ count
}}
204 Reads the specified number of bytes into a buffer, returning the actual number read.
206 \wxheading{Parameters
}
208 \docparam{buffer
}{A buffer to receive the data.
}
210 \docparam{count
}{The number of bytes to read.
}
212 \wxheading{Return value
}
214 The number of bytes read, or the symbol
{\bf wxInvalidOffset
} (-
1) if there was an error.
216 \membersection{wxFile::Seek
}\label{wxfileseek
}
218 \func{off
\_t}{Seek
}{\param{off
\_t }{ofs
},
\param{wxSeekMode
}{mode = wxFromStart
}}
220 Seeks to the specified position.
222 \wxheading{Parameters
}
224 \docparam{ofs
}{Offset to seek to.
}
226 \docparam{mode
}{One of
{\bf wxFromStart
},
{\bf wxFromEnd
},
{\bf wxFromCurrent
}.
}
228 \wxheading{Return value
}
230 The actual offset position achieved, or wxInvalidOffset on failure.
232 \membersection{wxFile::SeekEnd
}\label{wxfileseekend
}
234 \func{off
\_t}{SeekEnd
}{\param{off
\_t }{ofs =
0}}
236 Moves the file pointer to the specified number of bytes before the end of the file.
238 \wxheading{Parameters
}
240 \docparam{ofs
}{Number of bytes before the end of the file.
}
242 \wxheading{Return value
}
244 The actual offset position achieved, or wxInvalidOffset on failure.
246 \membersection{wxFile::Tell
}\label{wxfiletell
}
248 \constfunc{off
\_t}{Tell
}{\void}
250 Returns the current position or wxInvalidOffset if file is not opened or if another
253 \membersection{wxFile::Write
}\label{wxfilewrite
}
255 \func{bool
}{Write
}{\param{const void*
}{ buffer
},
\param{off
\_t}{ count
}}
257 Writes the specified number of bytes from a buffer.
259 \wxheading{Parameters
}
261 \docparam{buffer
}{A buffer containing the data.
}
263 \docparam{count
}{The number of bytes to write.
}
265 \wxheading{Return value
}
267 TRUE if the operation was successful.
269 \membersection{wxFile::Write
}\label{wxfilewrites
}
271 \func{bool
}{Write
}{\param{const wxString\&
}{s
}}
273 Writes the contents of the string to the file, returns TRUE on success.
275 \section{\class{wxFFile
}}\label{wxffile
}
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.
282 \wxheading{Derived from
}
286 \wxheading{Include files
}
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)
}
297 \latexignore{\rtfignore{\wxheading{Members
}}}
299 \membersection{wxFFile::wxFFile
}\label{wxffileconstr
}
301 \func{}{wxFFile
}{\void}
305 \func{}{wxFFile
}{\param{const char*
}{ filename
},
\param{const char*
}{ mode = "r"
}}
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
312 \func{}{wxFFile
}{\param{FILE*
}{ fp
}}
314 Opens a file with the given file pointer, which has already been opened.
316 \wxheading{Parameters
}
318 \docparam{filename
}{The filename.
}
320 \docparam{mode
}{The mode in which to open the file using standard C strings.
}
322 \docparam{fp
}{An existing file descriptor, such as stderr.
}
324 \membersection{wxFFile::
\destruct{wxFFile
}}
326 \func{}{\destruct{wxFFile
}}{\void}
328 Destructor will close the file.
330 NB: it is not virtual so you should
{\it not
} derive from wxFFile!
332 \membersection{wxFFile::Attach
}\label{wxffileattach
}
334 \func{void
}{Attach
}{\param{FILE*
}{ fp
}}
336 Attaches an existing file pointer to the wxFFile object.
338 The descriptor should be already opened and it will be closed by wxFFile
341 \membersection{wxFFile::Close
}\label{wxffileclose
}
343 \func{bool
}{Close
}{\void}
345 Closes the file and returns TRUE on success.
347 \membersection{wxFFile::Detach
}\label{wxffiledetach
}
349 \func{void
}{Detach
}{\void}
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().
354 \membersection{wxFFile::fp
}\label{wxffilefp
}
356 \constfunc{FILE *
}{fp
}{\void}
358 Returns the file pointer associated with the file.
360 \membersection{wxFFile::Eof
}\label{wxffileeof
}
362 \constfunc{bool
}{Eof
}{\void}
364 Returns TRUE if the an attempt has been made to read
{\it past
}
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
372 \membersection{wxFFile::Flush
}\label{wxffileflush
}
374 \func{bool
}{Flush
}{\void}
376 Flushes the file and returns TRUE on success.
378 \membersection{wxFFile::IsOpened
}\label{wxffileisopened
}
380 \constfunc{bool
}{IsOpened
}{\void}
382 Returns TRUE if the file has been opened.
384 \membersection{wxFFile::Length
}\label{wxffilelength
}
386 \constfunc{size
\_t}{Length
}{\void}
388 Returns the length of the file.
390 \membersection{wxFFile::Open
}\label{wxffileopen
}
392 \func{bool
}{Open
}{\param{const char*
}{ filename
},
\param{const char*
}{ mode = "r"
}}
394 Opens the file, returning TRUE if successful.
396 \wxheading{Parameters
}
398 \docparam{filename
}{The filename.
}
400 \docparam{mode
}{The mode in which to open the file.
}
402 \membersection{wxFFile::Read
}\label{wxffileread
}
404 \func{size
\_t}{Read
}{\param{void*
}{ buffer
},
\param{off
\_t}{ count
}}
406 Reads the specified number of bytes into a buffer, returning the actual number read.
408 \wxheading{Parameters
}
410 \docparam{buffer
}{A buffer to receive the data.
}
412 \docparam{count
}{The number of bytes to read.
}
414 \wxheading{Return value
}
416 The number of bytes read.
418 \membersection{wxFFile::Seek
}\label{wxffileseek
}
420 \func{bool
}{Seek
}{\param{long
}{ofs
},
\param{wxSeekMode
}{mode = wxFromStart
}}
422 Seeks to the specified position and returs TRUE on success.
424 \wxheading{Parameters
}
426 \docparam{ofs
}{Offset to seek to.
}
428 \docparam{mode
}{One of
{\bf wxFromStart
},
{\bf wxFromEnd
},
{\bf wxFromCurrent
}.
}
430 \membersection{wxFFile::SeekEnd
}\label{wxffileseekend
}
432 \func{bool
}{SeekEnd
}{\param{long
}{ofs =
0}}
434 Moves the file pointer to the specified number of bytes before the end of the file
435 and returns TRUE on success.
437 \wxheading{Parameters
}
439 \docparam{ofs
}{Number of bytes before the end of the file.
}
441 \membersection{wxFFile::Tell
}\label{wxffiletell
}
443 \constfunc{size
\_t}{Tell
}{\void}
445 Returns the current position.
447 \membersection{wxFFile::Write
}\label{wxffilewrite
}
449 \func{size_t
}{Write
}{\param{const void*
}{ buffer
},
\param{size
\_t}{ count
}}
451 Writes the specified number of bytes from a buffer.
453 \wxheading{Parameters
}
455 \docparam{buffer
}{A buffer containing the data.
}
457 \docparam{count
}{The number of bytes to write.
}
459 \wxheading{Return value
}
461 Number of bytes written.
463 \membersection{wxFFile::Write
}\label{wxffilewrites
}
465 \func{bool
}{Write
}{\param{const wxString\&
}{s
}}
467 Writes the contents of the string to the file, returns TRUE on success.