|  | Home · Overviews · Examples

# QFile Class Reference
[com.trolltech.qt.core module]

The `QFile` class provides an interface for reading from and writing to files. More...

Inherits `QIODevice`.

Inherited by `QTemporaryFile`.

## Detailed Description

The `QFile` class provides an interface for reading from and writing to files.

`QFile` is an I/O device for reading and writing text and binary files and resources. A `QFile` may be used by itself or, more conveniently, with a `QTextStream` or `QDataStream`.

The file name is usually passed in the constructor, but it can be set at any time using `setFileName`. `QFile` expects the file separator to be '/' regardless of operating system. The use of other separators (e.g., '\') is not supported.

You can check for a file's existence using `exists`, and remove a file using `remove`. (More advanced file system related operations are provided by `QFileInfo` and `QDir`.)

The file is opened with `open`, closed with `close`, and flushed with `flush`. Data is usually read and written using `QDataStream` or `QTextStream`, but you can also call the `QIODevice`-inherited functions `read`, `readLine`, `readAll`, `write`. `QFile` also inherits getChar(), putChar(), and ungetChar(), which work one character at a time.

The size of the file is returned by `size`. You can get the current file position using `pos`, or move to a new file position using `seek`. If you've reached the end of the file, `atEnd` returns true.

### Reading Files Directly

The following example reads a text file line by line:

            QFile file("in.txt");
            if (!file.open(QIODevice::ReadOnly | QIODevice::Text))
                return;

            while (!file.atEnd()) {
                QByteArray line = file.readLine();
                process_line(line);
            }

The QIODevice::Text flag passed to `open` tells Qt to convert Windows-style line terminators ("\r\n") into C++-style terminators ("\n"). By default, `QFile` assumes binary, i.e. it doesn't perform any conversion on the bytes stored in the file.

### Using Streams to Read Files

The next example uses `QTextStream` to read a text file line by line:

            QFile file("in.txt");
            if (!file.open(QIODevice::ReadOnly | QIODevice::Text))
                return;

            QTextStream in(&file);
            while (!in.atEnd()) {
                QString line = in.readLine();
                process_line(line);
            }

`QTextStream` takes care of converting the 8-bit data stored on disk into a 16-bit Unicode `QString`. By default, it assumes that the user system's local 8-bit encoding is used (e.g., ISO 8859-1 for most of Europe; see QTextCodec::codecForLocale() for details). This can be changed using setCodec().

To write text, we can use operator<<(), which is overloaded to take a `QTextStream` on the left and various data types (including `QString`) on the right:

            QFile file("out.txt");
            if (!file.open(QIODevice::WriteOnly | QIODevice::Text))
                return;

            QTextStream out(&file);
            out << "The magic number is: " << 49 << "\n";

`QDataStream` is similar, in that you can use operator<<() to write data and operator>>() to read it back. See the class documentation for details.

When you use `QFile`, `QFileInfo`, and `QDir` 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 use standard C++ APIs (`<cstdio>` or `<iostream>`) or platform-specific APIs to access files instead of `QFile`, you can use the `encodeName` and `decodeName` functions to convert between Unicode file names and 8-bit file names.

On Unix, there are some special system files (e.g. in `/proc`) for which `size` will always return 0, yet you may still be able to read more data from such a file; the data is generated in direct response to you calling `read`. In this case, however, you cannot use `atEnd` to determine if there is more data to read (since `atEnd` will return true for a file that claims to have size 0). Instead, you should either call `readAll`, or call `read` or `readLine` repeatedly until no more data can be read. The next example uses `QTextStream` to read `/proc/modules` line by line:

            QFile file("/proc/modules");
            if (!file.open(QIODevice::ReadOnly | QIODevice::Text))
                return;

            QTextStream in(&file);
            QString line = in.readLine();
            while (!line.isNull()) {
                process_line(line);
                line = in.readLine();
            }

### Signals

Unlike other `QIODevice` implementations, such as `QTcpSocket`, `QFile` does not emit the `aboutToClose`, `bytesWritten`, or `readyRead` signals. This implementation detail means that `QFile` is not suitable for reading and writing certain types of files, such as device files on Unix platforms.

See also `QTextStream`, `QDataStream`, `QFileInfo`, `QDir`, and The Qt Resource System.