You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
504 lines
28 KiB
504 lines
28 KiB
14 years ago
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
|
|
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/tools/qfile.cpp:77 -->
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||
|
|
<title>QFile Class</title>
|
||
|
|
<style type="text/css"><!--
|
||
|
|
fn { margin-left: 1cm; text-indent: -1cm; }
|
||
|
|
a:link { color: #004faf; text-decoration: none }
|
||
|
|
a:visited { color: #672967; text-decoration: none }
|
||
|
|
body { background: #ffffff; color: black; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
|
||
|
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
||
|
|
<tr bgcolor="#E5E5E5">
|
||
|
|
<td valign=center>
|
||
|
|
<a href="index.html">
|
||
|
|
<font color="#004faf">Home</font></a>
|
||
|
|
| <a href="classes.html">
|
||
|
|
<font color="#004faf">All Classes</font></a>
|
||
|
|
| <a href="mainclasses.html">
|
||
|
|
<font color="#004faf">Main Classes</font></a>
|
||
|
|
| <a href="annotated.html">
|
||
|
|
<font color="#004faf">Annotated</font></a>
|
||
|
|
| <a href="groups.html">
|
||
|
|
<font color="#004faf">Grouped Classes</font></a>
|
||
|
|
| <a href="functions.html">
|
||
|
|
<font color="#004faf">Functions</font></a>
|
||
|
|
</td>
|
||
|
|
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QFile Class Reference</h1>
|
||
|
|
|
||
|
|
<p>The QFile class is an I/O device that operates on files.
|
||
|
|
<a href="#details">More...</a>
|
||
|
|
<p>Almost all the functions in this class are <a href="threads.html#reentrant">reentrant</a> when Qt is built with thread support. The exceptions are <a href="#setEncodingFunction"><b>setEncodingFunction</b></a>(), <a href="#setDecodingFunction"><b>setDecodingFunction</b></a>(), and <a href="#setErrorString"><b>setErrorString</b></a>().
|
||
|
|
</p><p><tt>#include <<a href="qfile-h.html">qfile.h</a>></tt>
|
||
|
|
<p>Inherits <a href="qiodevice.html">QIODevice</a>.
|
||
|
|
<p><a href="qfile-members.html">List of all member functions.</a>
|
||
|
|
<h2>Public Members</h2>
|
||
|
|
<ul>
|
||
|
|
<li class=fn><a href="#QFile"><b>QFile</b></a> ()</li>
|
||
|
|
<li class=fn><a href="#QFile-2"><b>QFile</b></a> ( const QString & name )</li>
|
||
|
|
<li class=fn><a href="#~QFile"><b>~QFile</b></a> ()</li>
|
||
|
|
<li class=fn>QString <a href="#name"><b>name</b></a> () const</li>
|
||
|
|
<li class=fn>void <a href="#setName"><b>setName</b></a> ( const QString & name )</li>
|
||
|
|
<li class=fn>typedef QCString (* <a href="#EncoderFn"><b>EncoderFn</b></a> ) ( const QString & fileName )</li>
|
||
|
|
<li class=fn>typedef QString (* <a href="#DecoderFn"><b>DecoderFn</b></a> ) ( const QCString & localfileName )</li>
|
||
|
|
<li class=fn>bool <a href="#exists-2"><b>exists</b></a> () const</li>
|
||
|
|
<li class=fn>bool <a href="#remove"><b>remove</b></a> ()</li>
|
||
|
|
<li class=fn>virtual bool <a href="#open"><b>open</b></a> ( int m )</li>
|
||
|
|
<li class=fn>bool <a href="#open-2"><b>open</b></a> ( int m, FILE * f )</li>
|
||
|
|
<li class=fn>bool <a href="#open-3"><b>open</b></a> ( int m, int f )</li>
|
||
|
|
<li class=fn>virtual void <a href="#close"><b>close</b></a> ()</li>
|
||
|
|
<li class=fn>virtual void <a href="#flush"><b>flush</b></a> ()</li>
|
||
|
|
<li class=fn>virtual Offset <a href="#size"><b>size</b></a> () const</li>
|
||
|
|
<li class=fn>virtual bool <a href="#atEnd"><b>atEnd</b></a> () const</li>
|
||
|
|
<li class=fn>virtual Q_LONG <a href="#readLine"><b>readLine</b></a> ( char * p, Q_ULONG maxlen )</li>
|
||
|
|
<li class=fn>Q_LONG <a href="#readLine-2"><b>readLine</b></a> ( QString & s, Q_ULONG maxlen )</li>
|
||
|
|
<li class=fn>virtual int <a href="#getch"><b>getch</b></a> ()</li>
|
||
|
|
<li class=fn>virtual int <a href="#putch"><b>putch</b></a> ( int ch )</li>
|
||
|
|
<li class=fn>virtual int <a href="#ungetch"><b>ungetch</b></a> ( int ch )</li>
|
||
|
|
<li class=fn>int <a href="#handle"><b>handle</b></a> () const</li>
|
||
|
|
<li class=fn>QString <a href="#errorString"><b>errorString</b></a> () const</li>
|
||
|
|
</ul>
|
||
|
|
<h2>Static Public Members</h2>
|
||
|
|
<ul>
|
||
|
|
<li class=fn>QCString <a href="#encodeName"><b>encodeName</b></a> ( const QString & fileName )</li>
|
||
|
|
<li class=fn>QString <a href="#decodeName"><b>decodeName</b></a> ( const QCString & localFileName )</li>
|
||
|
|
<li class=fn>void <a href="#setEncodingFunction"><b>setEncodingFunction</b></a> ( EncoderFn f )</li>
|
||
|
|
<li class=fn>void <a href="#setDecodingFunction"><b>setDecodingFunction</b></a> ( DecoderFn f )</li>
|
||
|
|
<li class=fn>bool <a href="#exists"><b>exists</b></a> ( const QString & fileName )</li>
|
||
|
|
<li class=fn>bool <a href="#remove-2"><b>remove</b></a> ( const QString & fileName )</li>
|
||
|
|
</ul>
|
||
|
|
<h2>Important Inherited Members</h2>
|
||
|
|
<ul>
|
||
|
|
<li class=fn>virtual QByteArray <a href="#readAll"><b>readAll</b></a> ()</li>
|
||
|
|
</ul>
|
||
|
|
<h2>Protected Members</h2>
|
||
|
|
<ul>
|
||
|
|
<li class=fn>void <a href="#setErrorString"><b>setErrorString</b></a> ( const QString & str )</li>
|
||
|
|
</ul>
|
||
|
|
<hr><a name="details"></a><h2>Detailed Description</h2>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
The QFile class is an I/O device that operates on files.
|
||
|
|
<p>
|
||
|
|
|
||
|
|
<p> QFile is an I/O device for reading and writing binary and text
|
||
|
|
files. A QFile may be used by itself or more conveniently with a
|
||
|
|
<a href="qdatastream.html">QDataStream</a> or <a href="qtextstream.html">QTextStream</a>.
|
||
|
|
<p> The file name is usually passed in the constructor but can be
|
||
|
|
changed with <a href="#setName">setName</a>(). You can check for a file's existence with
|
||
|
|
<a href="#exists">exists</a>() and remove a file with <a href="#remove">remove</a>().
|
||
|
|
<p> The file is opened with <a href="#open">open</a>(), closed with <a href="#close">close</a>() and flushed
|
||
|
|
with <a href="#flush">flush</a>(). Data is usually read and written using QDataStream
|
||
|
|
or QTextStream, but you can read with <a href="qiodevice.html#readBlock">readBlock</a>() and <a href="#readLine">readLine</a>()
|
||
|
|
and write with <a href="qiodevice.html#writeBlock">writeBlock</a>(). QFile also supports <a href="#getch">getch</a>(),
|
||
|
|
<a href="#ungetch">ungetch</a>() and <a href="#putch">putch</a>().
|
||
|
|
<p> The size of the file is returned by <a href="#size">size</a>(). You can get the
|
||
|
|
current file position or move to a new file position using the
|
||
|
|
<a href="qiodevice.html#at">at</a>() functions. If you've reached the end of the file, <a href="#atEnd">atEnd</a>()
|
||
|
|
returns TRUE. The file handle is returned by <a href="#handle">handle</a>().
|
||
|
|
<p> Here is a code fragment that uses <a href="qtextstream.html">QTextStream</a> to read a text file
|
||
|
|
line by line. It prints each line with a line number.
|
||
|
|
<pre>
|
||
|
|
<a href="qstringlist.html">QStringList</a> lines;
|
||
|
|
QFile file( "file.txt" );
|
||
|
|
if ( file.<a href="#open">open</a>( IO_ReadOnly ) ) {
|
||
|
|
<a href="qtextstream.html">QTextStream</a> stream( &file );
|
||
|
|
<a href="qstring.html">QString</a> line;
|
||
|
|
int i = 1;
|
||
|
|
while ( !stream.<a href="qtextstream.html#atEnd">atEnd</a>() ) {
|
||
|
|
line = stream.<a href="qtextstream.html#readLine">readLine</a>(); // line of text excluding '\n'
|
||
|
|
printf( "%3d: %s\n", i++, line.<a href="qstring.html#latin1">latin1</a>() );
|
||
|
|
lines += line;
|
||
|
|
}
|
||
|
|
file.<a href="#close">close</a>();
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> Writing text is just as easy. The following example shows how to
|
||
|
|
write the data we read into the string list from the previous
|
||
|
|
example:
|
||
|
|
<pre>
|
||
|
|
QFile file( "file.txt" );
|
||
|
|
if ( file.<a href="#open">open</a>( IO_WriteOnly ) ) {
|
||
|
|
<a href="qtextstream.html">QTextStream</a> stream( &file );
|
||
|
|
for ( QStringList::Iterator it = lines.begin(); it != lines.end(); ++it )
|
||
|
|
stream << *it << "\n";
|
||
|
|
file.<a href="#close">close</a>();
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> The <a href="qfileinfo.html">QFileInfo</a> class holds detailed information about a file, such
|
||
|
|
as access permissions, file dates and file types.
|
||
|
|
<p> The <a href="qdir.html">QDir</a> class manages directories and lists of file names.
|
||
|
|
<p> Qt uses Unicode file names. If you want to do your own I/O on Unix
|
||
|
|
systems you may want to use <a href="#encodeName">encodeName</a>() (and <a href="#decodeName">decodeName</a>()) to
|
||
|
|
convert the file name into the local encoding.
|
||
|
|
<p>
|
||
|
|
<p> <p>See also <a href="qdatastream.html">QDataStream</a>, <a href="qtextstream.html">QTextStream</a>, and <a href="io.html">Input/Output and Networking</a>.
|
||
|
|
|
||
|
|
<hr><h2>Member Type Documentation</h2>
|
||
|
|
<h3 class=fn><a name="DecoderFn"></a>QFile::DecoderFn</h3>
|
||
|
|
|
||
|
|
<p> This is used by <a href="#setDecodingFunction">QFile::setDecodingFunction</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a name="EncoderFn"></a>QFile::EncoderFn</h3>
|
||
|
|
|
||
|
|
<p> This is used by <a href="#setEncodingFunction">QFile::setEncodingFunction</a>().
|
||
|
|
|
||
|
|
<hr><h2>Member Function Documentation</h2>
|
||
|
|
<h3 class=fn><a name="QFile"></a>QFile::QFile ()
|
||
|
|
</h3>
|
||
|
|
Constructs a QFile with no name.
|
||
|
|
|
||
|
|
<h3 class=fn><a name="QFile-2"></a>QFile::QFile ( const <a href="qstring.html">QString</a> & name )
|
||
|
|
</h3>
|
||
|
|
Constructs a QFile with a file name <em>name</em>.
|
||
|
|
<p> <p>See also <a href="#setName">setName</a>().
|
||
|
|
|
||
|
|
<h3 class=fn><a name="~QFile"></a>QFile::~QFile ()
|
||
|
|
</h3>
|
||
|
|
Destroys a QFile. Calls <a href="#close">close</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="atEnd"></a>QFile::atEnd () const<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Returns TRUE if the end of file has been reached; otherwise returns FALSE.
|
||
|
|
If QFile has not been <a href="#open">open</a>()'d, then the behavior is undefined.
|
||
|
|
<p> <p>See also <a href="#size">size</a>().
|
||
|
|
|
||
|
|
<p>Example: <a href="distributor-example.html#x2655">distributor/distributor.ui.h</a>.
|
||
|
|
<p>Reimplemented from <a href="qiodevice.html#atEnd">QIODevice</a>.
|
||
|
|
<h3 class=fn>void <a name="close"></a>QFile::close ()<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Closes an open file.
|
||
|
|
<p> The file is not closed if it was opened with an existing file handle.
|
||
|
|
If the existing file handle is a <tt>FILE*</tt>, the file is flushed.
|
||
|
|
If the existing file handle is an <tt>int</tt> file descriptor, nothing
|
||
|
|
is done to the file.
|
||
|
|
<p> Some "write-behind" filesystems may report an unspecified error on
|
||
|
|
closing the file. These errors only indicate that something may
|
||
|
|
have gone wrong since the previous <a href="#open">open</a>(). In such a case <a href="qiodevice.html#status">status</a>()
|
||
|
|
reports <a href="qiodevice.html#status">IO_UnspecifiedError</a> after <a href="#close">close</a>(), otherwise <a href="qiodevice.html#status">IO_Ok</a>.
|
||
|
|
<p> <p>See also <a href="#open">open</a>() and <a href="#flush">flush</a>().
|
||
|
|
|
||
|
|
<p>Examples: <a href="tutorial2-07.html#x2590">chart/chartform_files.cpp</a>, <a href="distributor-example.html#x2656">distributor/distributor.ui.h</a>, <a href="helpviewer-example.html#x987">helpviewer/helpwindow.cpp</a>, <a href="mdi-example.html#x2023">mdi/application.cpp</a>, <a href="qdir-example.html#x1814">qdir/qdir.cpp</a>, <a href="qwerty-example.html#x362">qwerty/qwerty.cpp</a>, and <a href="outliner-example.html#x1914">xml/outliner/outlinetree.cpp</a>.
|
||
|
|
<p>Reimplemented from <a href="qiodevice.html#close">QIODevice</a>.
|
||
|
|
<h3 class=fn><a href="qstring.html">QString</a> <a name="decodeName"></a>QFile::decodeName ( const <a href="qcstring.html">QCString</a> & localFileName )<tt> [static]</tt>
|
||
|
|
</h3>
|
||
|
|
This does the reverse of <a href="#encodeName">QFile::encodeName</a>() using <em>localFileName</em>.
|
||
|
|
<p> <p>See also <a href="#setDecodingFunction">setDecodingFunction</a>().
|
||
|
|
|
||
|
|
<p>Example: <a href="distributor-example.html#x2657">distributor/distributor.ui.h</a>.
|
||
|
|
<h3 class=fn><a href="qcstring.html">QCString</a> <a name="encodeName"></a>QFile::encodeName ( const <a href="qstring.html">QString</a> & fileName )<tt> [static]</tt>
|
||
|
|
</h3>
|
||
|
|
When you use QFile, <a href="qfileinfo.html">QFileInfo</a>, and <a href="qdir.html">QDir</a> to access the file system
|
||
|
|
with Qt, you can use Unicode file names. On Unix, these file names
|
||
|
|
are converted to an 8-bit encoding. If you want to do your own
|
||
|
|
file I/O on Unix, you should convert the file name using this
|
||
|
|
function. On Windows NT/2000, Unicode file names are supported
|
||
|
|
directly in the file system and this function should be avoided.
|
||
|
|
On Windows 95, non-Latin1 locales are not supported.
|
||
|
|
<p> By default, this function converts <em>fileName</em> to the local 8-bit
|
||
|
|
encoding determined by the user's locale. This is sufficient for
|
||
|
|
file names that the user chooses. File names hard-coded into the
|
||
|
|
application should only use 7-bit ASCII filename characters.
|
||
|
|
<p> The conversion scheme can be changed using <a href="#setEncodingFunction">setEncodingFunction</a>().
|
||
|
|
This might be useful if you wish to give the user an option to
|
||
|
|
store file names in UTF-8, etc., but be aware that such file names
|
||
|
|
would probably then be unrecognizable when seen by other programs.
|
||
|
|
<p> <p>See also <a href="#decodeName">decodeName</a>().
|
||
|
|
|
||
|
|
<p>Example: <a href="distributor-example.html#x2658">distributor/distributor.ui.h</a>.
|
||
|
|
<h3 class=fn><a href="qstring.html">QString</a> <a name="errorString"></a>QFile::errorString () const
|
||
|
|
</h3>
|
||
|
|
Returns a human-readable description of the reason of an error that occurred
|
||
|
|
on the device. The error described by the string corresponds to changes of
|
||
|
|
<a href="qiodevice.html#status">QIODevice::status</a>(). If the status is reset, the error string is also reset.
|
||
|
|
<p> The returned strings are not translated with the <a href="qobject.html#tr">QObject::tr</a>() or
|
||
|
|
<a href="qapplication.html#translate">QApplication::translate</a>() functions. They are marked as translatable
|
||
|
|
strings in the "QFile" context. Before you show the string to the user you
|
||
|
|
should translate it first, for example:
|
||
|
|
<p> <pre>
|
||
|
|
QFile f( "address.dat" );
|
||
|
|
if ( !f.<a href="#open">open</a>( <a href="qfile.html#open">IO_ReadOnly</a> ) {
|
||
|
|
QMessageBox::<a href="qmessagebox.html#critical">critical</a>(
|
||
|
|
this,
|
||
|
|
tr("Open failed"),
|
||
|
|
tr("Could not open file for reading: %1").arg( qApp-><a href="qapplication.html#translate">translate</a>("QFile",f.<a href="#errorString">errorString</a>()) )
|
||
|
|
);
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> <p>See also <a href="qiodevice.html#status">QIODevice::status</a>(), <a href="qiodevice.html#resetStatus">QIODevice::resetStatus</a>(), and <a href="#setErrorString">setErrorString</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="exists"></a>QFile::exists ( const <a href="qstring.html">QString</a> & fileName )<tt> [static]</tt>
|
||
|
|
</h3>
|
||
|
|
Returns TRUE if the file given by <em>fileName</em> exists; otherwise
|
||
|
|
returns FALSE.
|
||
|
|
|
||
|
|
<p>Examples: <a href="tutorial2-05.html#x2563">chart/chartform.cpp</a>, <a href="dirview-example.html#x1674">dirview/dirview.cpp</a>, and <a href="helpviewer-example.html#x988">helpviewer/helpwindow.cpp</a>.
|
||
|
|
<h3 class=fn>bool <a name="exists-2"></a>QFile::exists () const
|
||
|
|
</h3>
|
||
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Returns TRUE if this file exists; otherwise returns FALSE.
|
||
|
|
<p> <p>See also <a href="#name">name</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="flush"></a>QFile::flush ()<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Flushes the file buffer to the disk.
|
||
|
|
<p> <a href="#close">close</a>() also flushes the file buffer.
|
||
|
|
|
||
|
|
<p>Reimplemented from <a href="qiodevice.html#flush">QIODevice</a>.
|
||
|
|
<h3 class=fn>int <a name="getch"></a>QFile::getch ()<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Reads a single byte/character from the file.
|
||
|
|
<p> Returns the byte/character read, or -1 if the end of the file has
|
||
|
|
been reached.
|
||
|
|
<p> <p>See also <a href="#putch">putch</a>() and <a href="#ungetch">ungetch</a>().
|
||
|
|
|
||
|
|
<p>Reimplemented from <a href="qiodevice.html#getch">QIODevice</a>.
|
||
|
|
<h3 class=fn>int <a name="handle"></a>QFile::handle () const
|
||
|
|
</h3>
|
||
|
|
Returns the file handle of the file.
|
||
|
|
<p> This is a small positive integer, suitable for use with C library
|
||
|
|
functions such as fdopen() and fcntl(). On systems that use file
|
||
|
|
descriptors for sockets (ie. Unix systems, but not Windows) the handle
|
||
|
|
can be used with <a href="qsocketnotifier.html">QSocketNotifier</a> as well.
|
||
|
|
<p> If the file is not open or there is an error, <a href="#handle">handle</a>() returns -1.
|
||
|
|
<p> <p>See also <a href="qsocketnotifier.html">QSocketNotifier</a>.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qstring.html">QString</a> <a name="name"></a>QFile::name () const
|
||
|
|
</h3>
|
||
|
|
|
||
|
|
<p> Returns the name set by <a href="#setName">setName</a>().
|
||
|
|
<p> <p>See also <a href="#setName">setName</a>() and <a href="qfileinfo.html#fileName">QFileInfo::fileName</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="open"></a>QFile::open ( int m )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Opens the file specified by the file name currently set, using the
|
||
|
|
mode <em>m</em>. Returns TRUE if successful, otherwise FALSE.
|
||
|
|
<p> <!-- index IO_Raw --><!-- index IO_ReadOnly --><!-- index IO_WriteOnly --><!-- index IO_ReadWrite --><!-- index IO_Append --><!-- index IO_Truncate --><!-- index IO_Translate -->
|
||
|
|
<p> The mode parameter <em>m</em> must be a combination of the following flags:
|
||
|
|
<center><table cellpadding="4" cellspacing="2" border="0">
|
||
|
|
<tr bgcolor="#a2c511"> <th valign="top">Flag <th valign="top">Meaning
|
||
|
|
<tr bgcolor="#f0f0f0"> <td valign="top">IO_Raw
|
||
|
|
<td valign="top">Raw (non-buffered) file access.
|
||
|
|
<tr bgcolor="#d0d0d0"> <td valign="top">IO_ReadOnly
|
||
|
|
<td valign="top">Opens the file in read-only mode.
|
||
|
|
<tr bgcolor="#f0f0f0"> <td valign="top">IO_WriteOnly
|
||
|
|
<td valign="top">Opens the file in write-only mode. If this flag is used
|
||
|
|
with another flag, e.g. <a href="qfile.html#open">IO_ReadOnly</a> or <a href="qfile.html#open">IO_Raw</a> or <a href="qfile.html#open">IO_Append</a>, the file is <em>not</em> truncated; but if used on
|
||
|
|
its own (or with <a href="qfile.html#open">IO_Truncate</a>), the file is truncated.
|
||
|
|
<tr bgcolor="#d0d0d0"> <td valign="top">IO_ReadWrite
|
||
|
|
<td valign="top">Opens the file in read/write mode, equivalent to <tt>(IO_ReadOnly | IO_WriteOnly)</tt>.
|
||
|
|
<tr bgcolor="#f0f0f0"> <td valign="top">IO_Append
|
||
|
|
<td valign="top">Opens the file in append mode. (You must actually use <tt>(IO_WriteOnly | IO_Append)</tt> to make the file writable and
|
||
|
|
to go into append mode.) This mode is very useful when you
|
||
|
|
want to write something to a log file. The file index is
|
||
|
|
set to the end of the file. Note that the result is
|
||
|
|
undefined if you position the file index manually using
|
||
|
|
<a href="qiodevice.html#at">at</a>() in append mode.
|
||
|
|
<tr bgcolor="#d0d0d0"> <td valign="top">IO_Truncate
|
||
|
|
<td valign="top">Truncates the file.
|
||
|
|
<tr bgcolor="#f0f0f0"> <td valign="top">IO_Translate
|
||
|
|
<td valign="top">Enables carriage returns and linefeed translation for text
|
||
|
|
files under Windows.
|
||
|
|
</table></center>
|
||
|
|
<p> The raw access mode is best when I/O is block-operated using a 4KB
|
||
|
|
block size or greater. Buffered access works better when reading
|
||
|
|
small portions of data at a time.
|
||
|
|
<p> <b>Warning:</b> When working with buffered files, data may not be written
|
||
|
|
to the file at once. Call <a href="#flush">flush</a>() to make sure that the data is
|
||
|
|
really written.
|
||
|
|
<p> <b>Warning:</b> If you have a buffered file opened for both reading and
|
||
|
|
writing you must not perform an input operation immediately after
|
||
|
|
an output operation or vice versa. You should always call flush()
|
||
|
|
or a file positioning operation, e.g. at(), between input and
|
||
|
|
output operations, otherwise the buffer may contain garbage.
|
||
|
|
<p> If the file does not exist and <a href="qfile.html#open">IO_WriteOnly</a> or <a href="qfile.html#open">IO_ReadWrite</a>
|
||
|
|
is specified, it is created.
|
||
|
|
<p> Example:
|
||
|
|
<pre>
|
||
|
|
QFile f1( "/tmp/data.bin" );
|
||
|
|
f1.<a href="#open">open</a>( IO_Raw | IO_ReadWrite );
|
||
|
|
|
||
|
|
QFile f2( "readme.txt" );
|
||
|
|
f2.<a href="#open">open</a>( IO_ReadOnly | IO_Translate );
|
||
|
|
|
||
|
|
QFile f3( "audit.log" );
|
||
|
|
f3.<a href="#open">open</a>( IO_WriteOnly | IO_Append );
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> <p>See also <a href="#name">name</a>(), <a href="#close">close</a>(), <a href="qiodevice.html#isOpen">isOpen</a>(), and <a href="#flush">flush</a>().
|
||
|
|
|
||
|
|
<p>Examples: <a href="simple-application-example.html#x1548">application/application.cpp</a>, <a href="tutorial2-07.html#x2591">chart/chartform_files.cpp</a>, <a href="distributor-example.html#x2659">distributor/distributor.ui.h</a>, <a href="helpviewer-example.html#x989">helpviewer/helpwindow.cpp</a>, <a href="qdir-example.html#x1815">qdir/qdir.cpp</a>, <a href="qwerty-example.html#x363">qwerty/qwerty.cpp</a>, and <a href="outliner-example.html#x1915">xml/outliner/outlinetree.cpp</a>.
|
||
|
|
<p>Reimplemented from <a href="qiodevice.html#open">QIODevice</a>.
|
||
|
|
<h3 class=fn>bool <a name="open-2"></a>QFile::open ( int m, FILE * f )
|
||
|
|
</h3>
|
||
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Opens a file in the mode <em>m</em> using an existing file handle <em>f</em>.
|
||
|
|
Returns TRUE if successful, otherwise FALSE.
|
||
|
|
<p> Example:
|
||
|
|
<pre>
|
||
|
|
#include <stdio.h>
|
||
|
|
|
||
|
|
void printError( const char* msg )
|
||
|
|
{
|
||
|
|
QFile f;
|
||
|
|
f.<a href="#open">open</a>( <a href="qfile.html#open">IO_WriteOnly</a>, stderr );
|
||
|
|
f.<a href="qiodevice.html#writeBlock">writeBlock</a>( msg, qstrlen(msg) ); // write to stderr
|
||
|
|
f.<a href="#close">close</a>();
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> When a QFile is opened using this function, <a href="#close">close</a>() does not actually
|
||
|
|
close the file, only flushes it.
|
||
|
|
<p> <b>Warning:</b> If <em>f</em> is <tt>stdin</tt>, <tt>stdout</tt>, <tt>stderr</tt>, you may not
|
||
|
|
be able to seek. See <a href="qiodevice.html#isSequentialAccess">QIODevice::isSequentialAccess</a>() for more
|
||
|
|
information.
|
||
|
|
<p> <p>See also <a href="#close">close</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="open-3"></a>QFile::open ( int m, int f )
|
||
|
|
</h3>
|
||
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Opens a file in the mode <em>m</em> using an existing file descriptor <em>f</em>.
|
||
|
|
Returns TRUE if successful, otherwise FALSE.
|
||
|
|
<p> When a QFile is opened using this function, <a href="#close">close</a>() does not actually
|
||
|
|
close the file.
|
||
|
|
<p> The QFile that is opened using this function, is automatically set to be in
|
||
|
|
raw mode; this means that the file input/output functions are slow. If you
|
||
|
|
run into performance issues, you should try to use one of the other open
|
||
|
|
functions.
|
||
|
|
<p> <b>Warning:</b> If <em>f</em> is one of 0 (stdin), 1 (stdout) or 2 (stderr), you may not
|
||
|
|
be able to seek. <a href="#size">size</a>() is set to <tt>INT_MAX</tt> (in limits.h).
|
||
|
|
<p> <p>See also <a href="#close">close</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>int <a name="putch"></a>QFile::putch ( int ch )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Writes the character <em>ch</em> to the file.
|
||
|
|
<p> Returns <em>ch</em>, or -1 if some error occurred.
|
||
|
|
<p> <p>See also <a href="#getch">getch</a>() and <a href="#ungetch">ungetch</a>().
|
||
|
|
|
||
|
|
<p>Reimplemented from <a href="qiodevice.html#putch">QIODevice</a>.
|
||
|
|
<h3 class=fn><a href="qbytearray.html">QByteArray</a> <a name="readAll"></a>QIODevice::readAll ()<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
This convenience function returns all of the remaining data in the
|
||
|
|
device.
|
||
|
|
|
||
|
|
<h3 class=fn>Q_LONG <a name="readLine"></a>QFile::readLine ( char * p, Q_ULONG maxlen )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Reads a line of text.
|
||
|
|
<p> Reads bytes from the file into the char* <em>p</em>, until end-of-line
|
||
|
|
or <em>maxlen</em> bytes have been read, whichever occurs first. Returns
|
||
|
|
the number of bytes read, or -1 if there was an error. Any
|
||
|
|
terminating newline is not stripped.
|
||
|
|
<p> This function is only efficient for buffered files. Avoid
|
||
|
|
<a href="#readLine">readLine</a>() for files that have been opened with the <a href="qfile.html#open">IO_Raw</a>
|
||
|
|
flag.
|
||
|
|
<p> <p>See also <a href="qiodevice.html#readBlock">readBlock</a>() and <a href="qtextstream.html#readLine">QTextStream::readLine</a>().
|
||
|
|
|
||
|
|
<p>Reimplemented from <a href="qiodevice.html#readLine">QIODevice</a>.
|
||
|
|
<h3 class=fn>Q_LONG <a name="readLine-2"></a>QFile::readLine ( <a href="qstring.html">QString</a> & s, Q_ULONG maxlen )
|
||
|
|
</h3>
|
||
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Reads a line of text.
|
||
|
|
<p> Reads bytes from the file into string <em>s</em>, until end-of-line or
|
||
|
|
<em>maxlen</em> bytes have been read, whichever occurs first. Returns
|
||
|
|
the number of bytes read, or -1 if there was an error, e.g. end of
|
||
|
|
file. Any terminating newline is not stripped.
|
||
|
|
<p> This function is only efficient for buffered files. Avoid using
|
||
|
|
<a href="#readLine">readLine</a>() for files that have been opened with the <a href="qfile.html#open">IO_Raw</a>
|
||
|
|
flag.
|
||
|
|
<p> Note that the string is read as plain Latin1 bytes, not Unicode.
|
||
|
|
<p> <p>See also <a href="qiodevice.html#readBlock">readBlock</a>() and <a href="qtextstream.html#readLine">QTextStream::readLine</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="remove"></a>QFile::remove ()
|
||
|
|
</h3>
|
||
|
|
Removes the file specified by the file name currently set. Returns
|
||
|
|
TRUE if successful; otherwise returns FALSE.
|
||
|
|
<p> The file is closed before it is removed.
|
||
|
|
|
||
|
|
<h3 class=fn>bool <a name="remove-2"></a>QFile::remove ( const <a href="qstring.html">QString</a> & fileName )<tt> [static]</tt>
|
||
|
|
</h3>
|
||
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
||
|
|
<p> Removes the file <em>fileName</em>.
|
||
|
|
Returns TRUE if successful, otherwise FALSE.
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="setDecodingFunction"></a>QFile::setDecodingFunction ( <a href="qfile.html#DecoderFn">DecoderFn</a> f )<tt> [static]</tt>
|
||
|
|
</h3><p><b>Warning:</b> This function is <i>not</i> <a href="threads.html#reentrant">reentrant</a>.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<p> Sets the function for decoding 8-bit file names to <em>f</em>. The
|
||
|
|
default uses the locale-specific 8-bit encoding.
|
||
|
|
<p> <p>See also <a href="#encodeName">encodeName</a>() and <a href="#decodeName">decodeName</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="setEncodingFunction"></a>QFile::setEncodingFunction ( <a href="qfile.html#EncoderFn">EncoderFn</a> f )<tt> [static]</tt>
|
||
|
|
</h3><p><b>Warning:</b> This function is <i>not</i> <a href="threads.html#reentrant">reentrant</a>.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<p> Sets the function for encoding Unicode file names to <em>f</em>. The
|
||
|
|
default encodes in the locale-specific 8-bit encoding.
|
||
|
|
<p> <p>See also <a href="#encodeName">encodeName</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="setErrorString"></a>QFile::setErrorString ( const <a href="qstring.html">QString</a> & str )<tt> [protected]</tt>
|
||
|
|
</h3><p><b>Warning:</b> This function is <i>not</i> <a href="threads.html#reentrant">reentrant</a>.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<p> Sets the error string returned by the <a href="#errorString">errorString</a>() function to <em>str</em>.
|
||
|
|
<p> <p>See also <a href="#errorString">errorString</a>() and <a href="qiodevice.html#status">QIODevice::status</a>().
|
||
|
|
|
||
|
|
<h3 class=fn>void <a name="setName"></a>QFile::setName ( const <a href="qstring.html">QString</a> & name )
|
||
|
|
</h3>
|
||
|
|
Sets the name of the file to <em>name</em>. The name can have no path, a
|
||
|
|
relative path or an absolute absolute path.
|
||
|
|
<p> Do not call this function if the file has already been opened.
|
||
|
|
<p> If the file name has no path or a relative path, the path used
|
||
|
|
will be whatever the application's current directory path is
|
||
|
|
<em>at the time of the <a href="#open">open</a>()</em> call.
|
||
|
|
<p> Example:
|
||
|
|
<pre>
|
||
|
|
QFile file;
|
||
|
|
QDir::<a href="qdir.html#setCurrent">setCurrent</a>( "/tmp" );
|
||
|
|
file.<a href="#setName">setName</a>( "readme.txt" );
|
||
|
|
QDir::<a href="qdir.html#setCurrent">setCurrent</a>( "/home" );
|
||
|
|
file.<a href="#open">open</a>( <a href="qfile.html#open">IO_ReadOnly</a> ); // opens "/home/readme.txt" under Unix
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> Note that the directory separator "/" works for all operating
|
||
|
|
systems supported by Qt.
|
||
|
|
<p> <p>See also <a href="#name">name</a>(), <a href="qfileinfo.html">QFileInfo</a>, and <a href="qdir.html">QDir</a>.
|
||
|
|
|
||
|
|
<h3 class=fn><a href="qiodevice.html#Offset">Offset</a> <a name="size"></a>QFile::size () const<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Returns the file size.
|
||
|
|
<p>See also <a href="qiodevice.html#at">at</a>().
|
||
|
|
|
||
|
|
<p>Example: <a href="statistics-example.html#x2781">table/statistics/statistics.cpp</a>.
|
||
|
|
<p>Reimplemented from <a href="qiodevice.html#size">QIODevice</a>.
|
||
|
|
<h3 class=fn>int <a name="ungetch"></a>QFile::ungetch ( int ch )<tt> [virtual]</tt>
|
||
|
|
</h3>
|
||
|
|
Puts the character <em>ch</em> back into the file and decrements the
|
||
|
|
index if it is not zero.
|
||
|
|
<p> This function is normally called to "undo" a <a href="#getch">getch</a>() operation.
|
||
|
|
<p> Returns <em>ch</em>, or -1 if an error occurred.
|
||
|
|
<p> <p>See also <a href="#getch">getch</a>() and <a href="#putch">putch</a>().
|
||
|
|
|
||
|
|
<p>Reimplemented from <a href="qiodevice.html#ungetch">QIODevice</a>.
|
||
|
|
<!-- eof -->
|
||
|
|
<hr><p>
|
||
|
|
This file is part of the <a href="index.html">Qt toolkit</a>.
|
||
|
|
Copyright © 1995-2007
|
||
|
|
<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
|
||
|
|
<table width=100% cellspacing=0 border=0><tr>
|
||
|
|
<td>Copyright © 2007
|
||
|
|
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
||
|
|
<td align=right><div align=right>Qt 3.3.8</div>
|
||
|
|
</table></div></address></body>
|
||
|
|
</html>
|