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