1QFile(3qt) QFile(3qt)
2
6 QFile - I/O device that operates on files
7
9 Almost all the functions in this class are reentrant when Qt is built
10 with thread support. The exceptions are setEncodingFunction(),
11 setDecodingFunction(), and setErrorString(). </p>
12 #include <qfile.h>
14 Inherits QIODevice.
16 Public Members
18 QFile ()
19 QFile ( const QString & name )
20 ~QFile ()
21 QString name () const
22 void setName ( const QString & name )
23 typedef QCString (* EncoderFn ) ( const QString & fileName )
24 typedef QString (* DecoderFn ) ( const QCString & localfileName )
25 bool exists () const
26 bool remove ()
27 virtual bool open ( int m )
28 bool open ( int m, FILE * f )
29 bool open ( int m, int f )
30 virtual void close ()
31 virtual void flush ()
32 virtual Offset size () const
33 virtual bool atEnd () const
34 virtual Q_LONG readLine ( char * p, Q_ULONG maxlen )
35 Q_LONG readLine ( QString & s, Q_ULONG maxlen )
36 virtual int getch ()
37 virtual int putch ( int ch )
38 virtual int ungetch ( int ch )
39 int handle () const
40 QString errorString () const
41 Static Public Members
43 QCString encodeName ( const QString & fileName )
44 QString decodeName ( const QCString & localFileName )
45 void setEncodingFunction ( EncoderFn f )
46 void setDecodingFunction ( DecoderFn f )
47 bool exists ( const QString & fileName )
48 bool remove ( const QString & fileName )
49 Important Inherited Members
51 virtual QByteArray readAll ()
52 Protected Members
54 void setErrorString ( const QString & str )
55
57 The QFile class is an I/O device that operates on files.
58 QFile is an I/O device for reading and writing binary and text files. A
60 QFile may be used by itself or more conveniently with a QDataStream or
61 QTextStream.
62 The file name is usually passed in the constructor but can be changed
64 with setName(). You can check for a file's existence with exists() and
65 remove a file with remove().
66 The file is opened with open(), closed with close() and flushed with
68 flush(). Data is usually read and written using QDataStream or
69 QTextStream, but you can read with readBlock() and readLine() and write
70 with writeBlock(). QFile also supports getch(), ungetch() and putch().
71 The size of the file is returned by size(). You can get the current
73 file position or move to a new file position using the at() functions.
74 If you've reached the end of the file, atEnd() returns TRUE. The file
75 handle is returned by handle().
76 Here is a code fragment that uses QTextStream to read a text file line
78 by line. It prints each line with a line number.
79 QStringList lines;
81 QFile file( "file.txt" );
82 if ( file.open( IO_ReadOnly ) ) {
83 QTextStream stream( &file );
84 QString line;
85 int i = 1;
86 while ( !stream.atEnd() ) {
87 line = stream.readLine(); // line of text excluding '\n'
88 printf( "%3d: %s\n", i++, line.latin1() );
89 lines += line;
90 }
91 file.close();
92 }
93 Writing text is just as easy. The following example shows how to write
95 the data we read into the string list from the previous example:
96 QFile file( "file.txt" );
98 if ( file.open( IO_WriteOnly ) ) {
99 QTextStream stream( &file );
100 for ( QStringList::Iterator it = lines.begin(); it != lines.end(); ++it )
101 stream << *it << "\n";
102 file.close();
103 }
104 The QFileInfo class holds detailed information about a file, such as
106 access permissions, file dates and file types.
107 The QDir class manages directories and lists of file names.
109 Qt uses Unicode file names. If you want to do your own I/O on Unix
111 systems you may want to use encodeName() (and decodeName()) to convert
112 the file name into the local encoding.
113 See also QDataStream, QTextStream, and Input/Output and Networking.
115 Member Type Documentation
118 This is used by QFile::setDecodingFunction().
119
121 This is used by QFile::setEncodingFunction().
122
125 Constructs a QFile with no name.
126
128 Constructs a QFile with a file name name.
129 See also setName().
131
133 Destroys a QFile. Calls close().
134
136 Returns TRUE if the end of file has been reached; otherwise returns
137 FALSE. If QFile has not been open()'d, then the behavior is undefined.
138 See also size().
140 Example: distributor/distributor.ui.h.
142 Reimplemented from QIODevice.
144
146 Closes an open file.
147 The file is not closed if it was opened with an existing file handle.
149 If the existing file handle is a FILE*, the file is flushed. If the
150 existing file handle is an int file descriptor, nothing is done to the
151 file.
152 Some "write-behind" filesystems may report an unspecified error on
154 closing the file. These errors only indicate that something may have
155 gone wrong since the previous open(). In such a case status() reports
156 IO_UnspecifiedError after close(), otherwise IO_Ok.
157 See also open() and flush().
159 Examples:
161 Reimplemented from QIODevice.
163
165 This does the reverse of QFile::encodeName() using localFileName.
166 See also setDecodingFunction().
168 Example: distributor/distributor.ui.h.
170
172 When you use QFile, QFileInfo, and QDir to access the file system with
173 Qt, you can use Unicode file names. On Unix, these file names are
174 converted to an 8-bit encoding. If you want to do your own file I/O on
175 Unix, you should convert the file name using this function. On Windows
176 NT/2000, Unicode file names are supported directly in the file system
177 and this function should be avoided. On Windows 95, non-Latin1 locales
178 are not supported.
179 By default, this function converts fileName to the local 8-bit encoding
181 determined by the user's locale. This is sufficient for file names that
182 the user chooses. File names hard-coded into the application should
183 only use 7-bit ASCII filename characters.
184 The conversion scheme can be changed using setEncodingFunction(). This
186 might be useful if you wish to give the user an option to store file
187 names in UTF-8, etc., but be aware that such file names would probably
188 then be unrecognizable when seen by other programs.
189 See also decodeName().
191 Example: distributor/distributor.ui.h.
193
195 Returns a human-readable description of the reason of an error that
196 occurred on the device. The error described by the string corresponds
197 to changes of QIODevice::status(). If the status is reset, the error
198 string is also reset.
199 The returned strings are not translated with the QObject::tr() or
201 QApplication::translate() functions. They are marked as translatable
202 strings in the "QFile" context. Before you show the string to the user
203 you should translate it first, for example:
204 QFile f( "address.dat" );
206 if ( !f.open( IO_ReadOnly ) {
207 QMessageBox::critical(
208 this,
209 tr("Open failed"),
210 tr("Could not open file for reading: %1").arg( qApp->translate("QFile",f.errorString()) )
211 );
212 return;
213 }
214 See also QIODevice::status(), QIODevice::resetStatus(), and
216 setErrorString().
217
219 Returns TRUE if the file given by fileName exists; otherwise returns
220 FALSE.
221 Examples:
223
225 This is an overloaded member function, provided for convenience. It
226 behaves essentially like the above function.
227 Returns TRUE if this file exists; otherwise returns FALSE.
229 See also name().
231
233 Flushes the file buffer to the disk.
234 close() also flushes the file buffer.
236 Reimplemented from QIODevice.
238
240 Reads a single byte/character from the file.
241 Returns the byte/character read, or -1 if the end of the file has been
243 reached.
244 See also putch() and ungetch().
246 Reimplemented from QIODevice.
248
250 Returns the file handle of the file.
251 This is a small positive integer, suitable for use with C library
253 functions such as fdopen() and fcntl(). On systems that use file
254 descriptors for sockets (ie. Unix systems, but not Windows) the handle
255 can be used with QSocketNotifier as well.
256 If the file is not open or there is an error, handle() returns -1.
258 See also QSocketNotifier.
260
262 Returns the name set by setName().
263 See also setName() and QFileInfo::fileName().
265
267 Opens the file specified by the file name currently set, using the mode
268 m. Returns TRUE if successful, otherwise FALSE.
269 The mode parameter m must be a combination of the following flags:
271 <center>.nf
272 </center>
274 The raw access mode is best when I/O is block-operated using a 4KB
276 block size or greater. Buffered access works better when reading small
277 portions of data at a time.
278 Warning: When working with buffered files, data may not be written to
280 the file at once. Call flush() to make sure that the data is really
281 written.
282 Warning: If you have a buffered file opened for both reading and
284 writing you must not perform an input operation immediately after an
285 output operation or vice versa. You should always call flush() or a
286 file positioning operation, e.g. at(), between input and output
287 operations, otherwise the buffer may contain garbage.
288 If the file does not exist and IO_WriteOnly or IO_ReadWrite is
290 specified, it is created.
291 Example:
293 QFile f1( "/tmp/data.bin" );
295 f1.open( IO_Raw | IO_ReadWrite );
296 QFile f2( "readme.txt" );
297 f2.open( IO_ReadOnly | IO_Translate );
298 QFile f3( "audit.log" );
299 f3.open( IO_WriteOnly | IO_Append );
300 See also name(), close(), isOpen(), and flush().
302 Examples:
304 Reimplemented from QIODevice.
306
308 This is an overloaded member function, provided for convenience. It
309 behaves essentially like the above function.
310 Opens a file in the mode m using an existing file handle f. Returns
312 TRUE if successful, otherwise FALSE.
313 Example:
315 #include <stdio.h>
317 void printError( const char* msg )
318 {
319 QFile f;
320 f.open( IO_WriteOnly, stderr );
321 f.writeBlock( msg, qstrlen(msg) ); // write to stderr
322 f.close();
323 }
324 When a QFile is opened using this function, close() does not actually
326 close the file, only flushes it.
327 Warning: If f is stdin, stdout, stderr, you may not be able to seek.
329 See QIODevice::isSequentialAccess() for more information.
330 See also close().
332
334 This is an overloaded member function, provided for convenience. It
335 behaves essentially like the above function.
336 Opens a file in the mode m using an existing file descriptor f. Returns
338 TRUE if successful, otherwise FALSE.
339 When a QFile is opened using this function, close() does not actually
341 close the file.
342 The QFile that is opened using this function, is automatically set to
344 be in raw mode; this means that the file input/output functions are
345 slow. If you run into performance issues, you should try to use one of
346 the other open functions.
347 Warning: If f is one of 0 (stdin), 1 (stdout) or 2 (stderr), you may
349 not be able to seek. size() is set to INT_MAX (in limits.h).
350 See also close().
352
354 Writes the character ch to the file.
355 Returns ch, or -1 if some error occurred.
357 See also getch() and ungetch().
359 Reimplemented from QIODevice.
361
363 This convenience function returns all of the remaining data in the
364 device.
365
367 Reads a line of text.
368 Reads bytes from the file into the char* p, until end-of-line or maxlen
370 bytes have been read, whichever occurs first. Returns the number of
371 bytes read, or -1 if there was an error. Any terminating newline is not
372 stripped.
373 This function is only efficient for buffered files. Avoid readLine()
375 for files that have been opened with the IO_Raw flag.
376 See also readBlock() and QTextStream::readLine().
378 Reimplemented from QIODevice.
380
382 This is an overloaded member function, provided for convenience. It
383 behaves essentially like the above function.
384 Reads a line of text.
386 Reads bytes from the file into string s, until end-of-line or maxlen
388 bytes have been read, whichever occurs first. Returns the number of
389 bytes read, or -1 if there was an error, e.g. end of file. Any
390 terminating newline is not stripped.
391 This function is only efficient for buffered files. Avoid using
393 readLine() for files that have been opened with the IO_Raw flag.
394 Note that the string is read as plain Latin1 bytes, not Unicode.
396 See also readBlock() and QTextStream::readLine().
398
400 Removes the file specified by the file name currently set. Returns TRUE
401 if successful; otherwise returns FALSE.
402 The file is closed before it is removed.
404
406 This is an overloaded member function, provided for convenience. It
407 behaves essentially like the above function.
408 Removes the file fileName. Returns TRUE if successful, otherwise FALSE.
410
412 Warning: This function is not reentrant.</p>
413 Sets the function for decoding 8-bit file names to f. The default uses
415 the locale-specific 8-bit encoding.
416 See also encodeName() and decodeName().
418
420 Warning: This function is not reentrant.</p>
421 Sets the function for encoding Unicode file names to f. The default
423 encodes in the locale-specific 8-bit encoding.
424 See also encodeName().
426
428 Warning: This function is not reentrant.</p>
429 Sets the error string returned by the errorString() function to str.
431 See also errorString() and QIODevice::status().
433
435 Sets the name of the file to name. The name can have no path, a
436 relative path or an absolute absolute path.
437 Do not call this function if the file has already been opened.
439 If the file name has no path or a relative path, the path used will be
441 whatever the application's current directory path is at the time of the
442 open() call.
443 Example:
445 QFile file;
447 QDir::setCurrent( "/tmp" );
448 file.setName( "readme.txt" );
449 QDir::setCurrent( "/home" );
450 file.open( IO_ReadOnly ); // opens "/home/readme.txt" under Unix
451 Note that the directory separator "/" works for all operating systems
453 supported by Qt.
454 See also name(), QFileInfo, and QDir.
456
458 Returns the file size.
459 See also at().
461 Example: table/statistics/statistics.cpp.
463 Reimplemented from QIODevice.
465
467 Puts the character ch back into the file and decrements the index if it
468 is not zero.
469 This function is normally called to "undo" a getch() operation.
471 Returns ch, or -1 if an error occurred.
473 See also getch() and putch().
475 Reimplemented from QIODevice.
477
480 http://doc.trolltech.com/qfile.html
481 http://www.trolltech.com/faq/tech.html
482
484 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
485 license file included in the distribution for a complete license
486 statement.
487
489 Generated automatically from the source code.
490
492 If you find a bug in Qt, please report it as described in
493 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
494 help you. Thank you.
495 The definitive Qt documentation is provided in HTML format; it is
497 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
498 web browser. This man page is provided as a convenience for those users
499 who prefer man pages, although this format is not officially supported
500 by Trolltech.
501 If you find errors in this manual page, please report them to qt-
503 bugs@trolltech.com. Please include the name of the manual page
504 (qfile.3qt) and the Qt version (3.3.8).
505Trolltech AS 2 February 2007 QFile(3qt)