1QFile(3qt)                                                          QFile(3qt)
2
3
4

NAME

6       QFile - I/O device that operates on files
7

SYNOPSIS

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
13       #include <qfile.h>
14
15       Inherits QIODevice.
16
17   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
42   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
50   Important Inherited Members
51       virtual QByteArray readAll ()
52
53   Protected Members
54       void setErrorString ( const QString & str )
55

DESCRIPTION

57       The QFile class is an I/O device that operates on files.
58
59       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
63       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
67       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
72       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
77       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
80           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
94       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
97           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
105       The QFileInfo class holds detailed information about a file, such as
106       access permissions, file dates and file types.
107
108       The QDir class manages directories and lists of file names.
109
110       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
114       See also QDataStream, QTextStream, and Input/Output and Networking.
115
116   Member Type Documentation

QFile::DecoderFn

118       This is used by QFile::setDecodingFunction().
119

QFile::EncoderFn

121       This is used by QFile::setEncodingFunction().
122

MEMBER FUNCTION DOCUMENTATION

QFile::QFile ()

125       Constructs a QFile with no name.
126

QFile::QFile ( const QString & name )

128       Constructs a QFile with a file name name.
129
130       See also setName().
131

QFile::~QFile ()

133       Destroys a QFile. Calls close().
134

bool QFile::atEnd () const [virtual]

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
139       See also size().
140
141       Example: distributor/distributor.ui.h.
142
143       Reimplemented from QIODevice.
144

void QFile::close () [virtual]

146       Closes an open file.
147
148       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
153       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
158       See also open() and flush().
159
160       Examples:
161
162       Reimplemented from QIODevice.
163

QString QFile::decodeName ( const QCString & localFileName ) [static]

165       This does the reverse of QFile::encodeName() using localFileName.
166
167       See also setDecodingFunction().
168
169       Example: distributor/distributor.ui.h.
170

QCString QFile::encodeName ( const QString & fileName ) [static]

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
180       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
185       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
190       See also decodeName().
191
192       Example: distributor/distributor.ui.h.
193

QString QFile::errorString () const

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
200       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
205               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
215       See also QIODevice::status(), QIODevice::resetStatus(), and
216       setErrorString().
217

bool QFile::exists ( const QString & fileName ) [static]

219       Returns TRUE if the file given by fileName exists; otherwise returns
220       FALSE.
221
222       Examples:
223

bool QFile::exists () const

225       This is an overloaded member function, provided for convenience. It
226       behaves essentially like the above function.
227
228       Returns TRUE if this file exists; otherwise returns FALSE.
229
230       See also name().
231

void QFile::flush () [virtual]

233       Flushes the file buffer to the disk.
234
235       close() also flushes the file buffer.
236
237       Reimplemented from QIODevice.
238

int QFile::getch () [virtual]

240       Reads a single byte/character from the file.
241
242       Returns the byte/character read, or -1 if the end of the file has been
243       reached.
244
245       See also putch() and ungetch().
246
247       Reimplemented from QIODevice.
248

int QFile::handle () const

250       Returns the file handle of the file.
251
252       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
257       If the file is not open or there is an error, handle() returns -1.
258
259       See also QSocketNotifier.
260

QString QFile::name () const

262       Returns the name set by setName().
263
264       See also setName() and QFileInfo::fileName().
265

bool QFile::open ( int m ) [virtual]

267       Opens the file specified by the file name currently set, using the mode
268       m. Returns TRUE if successful, otherwise FALSE.
269
270       The mode parameter m must be a combination of the following flags:
271       <center>.nf
272
273       </center>
274
275       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
279       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
283       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
289       If the file does not exist and IO_WriteOnly or IO_ReadWrite is
290       specified, it is created.
291
292       Example:
293
294               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
301       See also name(), close(), isOpen(), and flush().
302
303       Examples:
304
305       Reimplemented from QIODevice.
306

bool QFile::open ( int m, FILE * f )

308       This is an overloaded member function, provided for convenience. It
309       behaves essentially like the above function.
310
311       Opens a file in the mode m using an existing file handle f. Returns
312       TRUE if successful, otherwise FALSE.
313
314       Example:
315
316           #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
325       When a QFile is opened using this function, close() does not actually
326       close the file, only flushes it.
327
328       Warning: If f is stdin, stdout, stderr, you may not be able to seek.
329       See QIODevice::isSequentialAccess() for more information.
330
331       See also close().
332

bool QFile::open ( int m, int f )

334       This is an overloaded member function, provided for convenience. It
335       behaves essentially like the above function.
336
337       Opens a file in the mode m using an existing file descriptor f. Returns
338       TRUE if successful, otherwise FALSE.
339
340       When a QFile is opened using this function, close() does not actually
341       close the file.
342
343       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
348       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
351       See also close().
352

int QFile::putch ( int ch ) [virtual]

354       Writes the character ch to the file.
355
356       Returns ch, or -1 if some error occurred.
357
358       See also getch() and ungetch().
359
360       Reimplemented from QIODevice.
361

QByteArray QIODevice::readAll () [virtual]

363       This convenience function returns all of the remaining data in the
364       device.
365

Q_LONG QFile::readLine ( char * p, Q_ULONG maxlen ) [virtual]

367       Reads a line of text.
368
369       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
374       This function is only efficient for buffered files. Avoid readLine()
375       for files that have been opened with the IO_Raw flag.
376
377       See also readBlock() and QTextStream::readLine().
378
379       Reimplemented from QIODevice.
380

Q_LONG QFile::readLine ( QString & s, Q_ULONG maxlen )

382       This is an overloaded member function, provided for convenience. It
383       behaves essentially like the above function.
384
385       Reads a line of text.
386
387       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
392       This function is only efficient for buffered files. Avoid using
393       readLine() for files that have been opened with the IO_Raw flag.
394
395       Note that the string is read as plain Latin1 bytes, not Unicode.
396
397       See also readBlock() and QTextStream::readLine().
398

bool QFile::remove ()

400       Removes the file specified by the file name currently set. Returns TRUE
401       if successful; otherwise returns FALSE.
402
403       The file is closed before it is removed.
404

bool QFile::remove ( const QString & fileName ) [static]

406       This is an overloaded member function, provided for convenience. It
407       behaves essentially like the above function.
408
409       Removes the file fileName. Returns TRUE if successful, otherwise FALSE.
410

void QFile::setDecodingFunction ( DecoderFn f ) [static]

412       Warning: This function is not reentrant.</p>
413
414       Sets the function for decoding 8-bit file names to f. The default uses
415       the locale-specific 8-bit encoding.
416
417       See also encodeName() and decodeName().
418

void QFile::setEncodingFunction ( EncoderFn f ) [static]

420       Warning: This function is not reentrant.</p>
421
422       Sets the function for encoding Unicode file names to f. The default
423       encodes in the locale-specific 8-bit encoding.
424
425       See also encodeName().
426

void QFile::setErrorString ( const QString & str ) [protected]

428       Warning: This function is not reentrant.</p>
429
430       Sets the error string returned by the errorString() function to str.
431
432       See also errorString() and QIODevice::status().
433

void QFile::setName ( const QString & name )

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
438       Do not call this function if the file has already been opened.
439
440       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
444       Example:
445
446               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
452       Note that the directory separator "/" works for all operating systems
453       supported by Qt.
454
455       See also name(), QFileInfo, and QDir.
456

Offset QFile::size () const [virtual]

458       Returns the file size.
459
460       See also at().
461
462       Example: table/statistics/statistics.cpp.
463
464       Reimplemented from QIODevice.
465

int QFile::ungetch ( int ch ) [virtual]

467       Puts the character ch back into the file and decrements the index if it
468       is not zero.
469
470       This function is normally called to "undo" a getch() operation.
471
472       Returns ch, or -1 if an error occurred.
473
474       See also getch() and putch().
475
476       Reimplemented from QIODevice.
477
478

SEE ALSO

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

AUTHOR

489       Generated automatically from the source code.
490

BUGS

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
496       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
502       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).
505
506
507
508Trolltech AS                    2 February 2007                     QFile(3qt)
Impressum