Класс QFile

Класс QFile предоставляет интерфейс для чтения и записи файлов. Подробнее...

• Список всех членов, включая унаследованные
• Устаревшие члены

Примечание: Все функции в этом классе являются перевходными.

Общие типы

Общедоступные функции

Переопределённые общедоступные функции

Статические общедоступные члены

Подробное описание

QFile — это устройство ввода-вывода для чтения и записи текстовых и двоичных файлов и ресурсов. Класс QFile может использоваться сам по себе или, что удобнее, с QTextStream или QDataStream.

Имя файла обычно передаётся в конструкторе, но его можно изменить в любой момент с помощью setFileName(). QFile ожидает, что разделитель файлов будет '/', независимо от операционной системы. Использование других разделителей (например, '\') не поддерживается.

Вы можете проверить наличие файла с помощью exists() и удалить файл с помощью remove(). (Более сложные операции с файловой системой предоставляются классами QFileInfo и QDir.)

Файл открывается с помощью open(), закрывается с помощью close() и очищается с помощью flush(). Данные обычно читаются и записываются с помощью QDataStream или QTextStream, но вы также можете вызвать унаследованные от QIODevice функции read(), readLine(), readAll(), write(). Класс QFile также наследует getChar(), putChar() и ungetChar(), которые работают с одним символом за раз.

Размер файла возвращается функцией size(). Текущую позицию в файле можно получить с помощью pos(), или переместить к новой позиции с помощью seek(). Если достигнут конец файла, функция atEnd() возвращает true.

Чтение файлов напрямую

Следующий пример читает текстовый файл построчно:

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

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

Флаг QIODevice::Text, переданный в open(), сообщает Qt о преобразовании символов новой строки Windows-формата ("\r\n") в символы новой строки C++-формата ("\n"). По умолчанию, QFile предполагает двоичный режим, то есть не выполняет преобразования байтов, хранящихся в файле.

Использование потоков для чтения файлов

Следующий пример использует QTextStream для чтения текстового файла построчно:

    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 позаботится о преобразовании 8-битных данных, хранящихся на диске, в 16-битный Unicode QString. По умолчанию, предполагается, что используется локальное 8-битное кодирование пользовательской системы (например, UTF-8 на большинстве систем на основе Unix; см. QTextCodec::codecForLocale() для получения подробностей). Это можно изменить с помощью QTextStream::setCodec().

Для записи текста можно использовать оператор<<(), перегруженный для работы с QTextStream слева и различными типами данных (включая QString) справа:

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

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

QDataStream аналогичен, в котором вы можете использовать оператор<<() для записи данных и оператор>>() для их последующего чтения. Подробности см. в документации к классу.

При использовании QFile, QFileInfo и QDir для доступа к файловой системе с Qt, вы можете использовать имена файлов Unicode. В Unix эти имена файлов преобразуются в 8-битное кодирование. Если вы хотите использовать стандартные C++ API (<cstdio> или <iostream>) или платформенно-специфические API для доступа к файлам вместо QFile, вы можете использовать функции encodeName() и decodeName() для преобразования между именами файлов Unicode и именами файлов в 8-битном кодировании.

В Unix существуют некоторые специальные системные файлы (например, в /proc), для которых size() всегда возвращает 0, но вы всё равно можете прочитать больше данных из такого файла; данные генерируются непосредственно в ответ на вызов read(). Однако в этом случае вы не можете использовать atEnd() для определения наличия дополнительных данных для чтения (так как atEnd() вернёт true для файла, который заявляет о размере 0). Вместо этого вы должны либо вызвать readAll(), либо вызвать read() или readLine() повторно до тех пор, пока больше данных не будет. Следующий пример использует QTextStream для чтения /proc/modules построчно:

    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();
    }

Сигналы

В отличие от других реализаций QIODevice, таких как QTcpSocket, QFile не излучает сигналы aboutToClose(), bytesWritten() или readyRead(). Эта особенность реализации означает, что QFile не подходит для чтения и записи определённых типов файлов, таких как файлы устройств в Unix-подобных платформах.

Особенности разных платформ

Права доступа к файлам обрабатываются по-разному в системах Unix-подобных и Windows. В каталогах без права записи в Unix-подобных системах нельзя создавать файлы. Это не всегда так в Windows, где, например, каталог «Мои документы» обычно не имеет права записи, но в нём всё равно можно создавать файлы.

Понимание Qt прав доступа к файлам ограничено, что особенно влияет на функцию QFile::setPermissions(). В Windows Qt устанавливает только устаревшую метку «только для чтения», и только когда ни один из флагов Write* не передан. Qt не манипулирует списками управления доступом (ACL), что делает эту функцию в основном бесполезной для томов NTFS. Она может быть полезна для USB-накопителей, использующих файловые системы VFAT. POSIX ACL также не изменяются.

См. также QTextStream, QDataStream, QFileInfo, QDir и Систему ресурсов Qt.

Документация по типам элементов

typedef QFile::DecoderFn

Это псевдоним для указателя на функцию со следующим сигнатурой:

QString myDecoderFunc(const QByteArray &localFileName);

См. также setDecodingFunction().

Документация по функциям

QFile::QFile(const QString &name, QObject *parent)

Создаёт новый объект файла с заданным parent для представления файла с указанным именем name.

QFile::QFile(QObject *parent)

Создаёт новый объект файла с заданным parent.

QFile::QFile(const QString &name)

Создаёт новый объект файла для представления файла с заданным именем name.

QFile::QFile()

Создаёт объект QFile.

[virtual] QFile::~QFile()

Удаляет объект файла, закрывая его при необходимости.

bool QFile::copy(const QString &newName)

Копирует файл, текущее имя которого задано в fileName(), в файл с именем newName. Возвращает true при успехе; в противном случае возвращает false.

Обратите внимание, что если файл с именем newName уже существует, copy() возвращает false (т. е. QFile не перезапишет его).

Исходный файл закрывается перед копированием.

См. также setFileName().

[static] bool QFile::copy(const QString &fileName, const QString &newName)

Это перегруженная функция.

Копирует файл fileName в newName. Возвращает true при успехе; в противном случае возвращает false.

Если файл с именем newName уже существует, copy() возвращает false (т. е., QFile не перезапишет его).

См. также rename().

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

Выполняет обратное действие по отношению к QFile::encodeName() с использованием localFileName.

См. также encodeName().

[static] QString QFile::decodeName(const char *localFileName)

Это перегруженная функция.

Возвращает Unicode-версию заданного localFileName. См. encodeName() для получения подробностей.

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

Преобразует fileName в локальное 8-битное кодирование, определяемое локалью пользователя. Это достаточно для имён файлов, выбираемых пользователем. Имена файлов, жёстко заданные в приложении, должны использовать только символы 7-битной ASCII.

См. также decodeName().

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

Возвращает true, если файл, указанный в fileName, существует; в противном случае возвращает false.

Примечание: Если fileName — символическая ссылка, указывающая на несуществующий файл, возвращается false.

bool QFile::exists() const

Это перегруженная функция.

Возвращает true, если файл, указанный в fileName(), существует; в противном случае возвращает false.

См. также fileName() и setFileName().

[override virtual] QString QFile::fileName() const

Переопределяет: QFileDevice::fileName() const.

Возвращает имя, заданное функцией setFileName() или конструкторами QFile.

См. также setFileName() и QFileInfo::fileName().

bool QFile::link(const QString &linkName)

Создаёт ссылку с именем linkName, указывающую на файл, текущее имя которого задано в fileName(). Характер ссылки зависит от файловой системы (это может быть ярлык в Windows или символическая ссылка в Unix). Возвращает true при успехе; в противном случае возвращает false.

Функция не перезапишет уже существующий элемент в файловой системе; в этом случае link() вернёт false и установит error() на RenameError.

Примечание: Для создания корректной ссылки в Windows linkName должно иметь .lnk расширение файла.

См. также setFileName().

[static] bool QFile::link(const QString &fileName, const QString &linkName)

Это перегруженная функция.

Создаёт ссылку с именем linkName, указывающую на файл fileName. Характер ссылки зависит от файловой системы (это может быть ярлык в Windows или символическая ссылка в Unix). Возвращает true при успехе; в противном случае возвращает false.

См. также link().

[override virtual] bool QFile::open(QIODevice::OpenMode mode)

Переопределяет: QIODevice::open(QIODevice::OpenMode mode).

Открывает файл, используя режим mode, возвращая true при успехе; в противном случае false.

mode должен быть QIODevice::ReadOnly, QIODevice::WriteOnly или QIODevice::ReadWrite. Он также может иметь дополнительные флаги, такие как QIODevice::Text и QIODevice::Unbuffered.

Примечание: В режимах WriteOnly или ReadWrite, если соответствующий файл ещё не существует, эта функция попытается создать новый файл перед его открытием.

См. также QIODevice::OpenMode и setFileName().

bool QFile::open(FILE *fh, QIODevice::OpenMode mode, QFileDevice::FileHandleFlags handleFlags = DontCloseHandle)

Это перегруженная функция.

Открывает существующий дескриптор файла fh в заданном режиме mode. handleFlags могут использоваться для указания дополнительных параметров. Возвращает true при успехе; в противном случае возвращает false.

Пример:

#include <stdio.h>

void printError(const char* msg)
{
    QFile file;
    file.open(stderr, QIODevice::WriteOnly);
    file.write(msg, qstrlen(msg));        // write to stderr
    file.close();
}

При открытии файла QFile с помощью этой функции, поведение метода close() контролируется флагом AutoCloseHandle. Если флаг AutoCloseHandle указан, и функция выполняется успешно, то вызов close() закрывает принятый дескриптор. В противном случае, close() не закрывает файл, а только производит его сброс.

Предупреждение:

1. Если fh не ссылается на обычный файл, например, если это stdin, stdout или stderr, возможно, вы не сможете использовать seek(). size() вернёт 0 в этих случаях. Для получения дополнительной информации обратитесь к QIODevice::isSequential().
2. Поскольку эта функция открывает файл без указания имени файла, вы не сможете использовать этот объект QFile с QFileInfo.

Примечание для платформы Windows

fh должен быть открыт в двоичном режиме (т.е. строка режима должна содержать 'b', как в "rb" или "wb"), при работе с файлами и другими устройствами произвольного доступа. Qt будет переводить символы конца строки, если вы передадите QIODevice::Text в mode. Последовательные устройства, такие как stdin и stdout, на это ограничение не влияют.

Для использования потоков stdin, stdout и stderr в консольных приложениях необходимо включить поддержку консольных приложений. Для этого добавьте следующую декларацию в файл проекта вашего приложения:

CONFIG += console

См. также close().

bool QFile::open(int fd, QIODevice::OpenMode mode, QFileDevice::FileHandleFlags handleFlags = DontCloseHandle)

Это перегруженный метод.

Открывает существующий дескриптор файла fd в заданном mode. handleFlags можно использовать для указания дополнительных опций. Возвращает true при успешном выполнении; в противном случае возвращает false.

При открытии файла QFile с помощью этой функции, поведение метода close() контролируется флагом AutoCloseHandle. Если флаг AutoCloseHandle указан, и функция выполняется успешно, то вызов close() закрывает принятый дескриптор. В противном случае, close() не закрывает файл, а только производит его сброс.

Файл QFile, открытый с помощью этой функции, автоматически устанавливается в сырой режим; это означает, что функции ввода-вывода файлов работают медленно. При возникновении проблем с производительностью, попробуйте использовать одну из других функций открытия.

Предупреждение: Если fd не является обычным файлом, например, это 0 (stdin), 1 (stdout) или 2 (stderr), вы, возможно, не сможете использовать seek(). В этих случаях size() возвращает 0. Для получения дополнительной информации обратитесь к QIODevice::isSequential().

Предупреждение: Поскольку эта функция открывает файл без указания имени файла, вы не сможете использовать этот объект QFile с QFileInfo.

См. также close().

[override virtual] QFileDevice::Permissions QFile::permissions() const

Переопределяет: QFileDevice::permissions() const.

См. также setPermissions().

[static] QFileDevice::Permissions QFile::permissions(const QString &fileName)

Это перегруженный метод.

Возвращает полное значение, полученное объединением по оператору OR, QFile::Permission для fileName.

bool QFile::remove()

Удаляет файл, указанный в fileName(). Возвращает true при успешном выполнении; в противном случае возвращает false.

Файл закрывается перед удалением.

См. также setFileName().

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

Это перегруженный метод.

Удаляет файл, указанный в fileName.

Возвращает true при успешном выполнении; в противном случае возвращает false.

См. также remove().

bool QFile::rename(const QString &newName)

Переименовывает файл, текущее имя которого задано в fileName(), в newName. Возвращает true при успешном выполнении; в противном случае возвращает false.

Если файл с именем newName уже существует, rename() возвращает false (т.е. QFile не перезапишет его).

Файл закрывается перед переименованием.

Если операция переименования завершается неудачно, Qt попытается скопировать содержимое файла в newName, а затем удалить исходный файл, оставив только newName. Если операция копирования или удаления исходного файла завершается неудачей, файл newName удаляется, чтобы восстановить предыдущее состояние.

См. также setFileName().

[static] bool QFile::rename(const QString &oldName, const QString &newName)

Это перегруженный метод.

Переименовывает файл oldName в newName. Возвращает true при успешном выполнении; в противном случае возвращает false.

Если файл с именем newName уже существует, rename() возвращает false (т.е. QFile не перезапишет его).

См. также rename().

[override virtual] bool QFile::resize(qint64 sz)

Переопределяет: QFileDevice::resize(qint64 sz).

[static] bool QFile::resize(const QString &fileName, qint64 sz)

Это перегруженный метод.

Устанавливает размер файла fileName в sz байт. Возвращает true, если изменение размера файла прошло успешно; в противном случае — false. Если sz больше текущего размера файла, новые байты будут установлены в 0; если sz меньше, файл просто обрезается.

Предупреждение: Эта функция может завершиться неудачей, если файл не существует.

См. также resize().

void QFile::setFileName(const QString &name)

Устанавливает имя файла name. Имя может быть без пути, относительным или абсолютным.

Не вызывайте эту функцию, если файл уже открыт.

Если имя файла не содержит путь или содержит относительный путь, используемый путь будет текущим каталогом приложения на момент вызова open().

Пример:

QFile file;
QDir::setCurrent("/tmp");
file.setFileName("readme.txt");
QDir::setCurrent("/home");
file.open(QIODevice::ReadOnly);      // opens "/home/readme.txt" under Unix

Обратите внимание, что разделитель каталогов "/" работает на всех операционных системах, поддерживаемых Qt.

См. также fileName(), QFileInfo и QDir.

[override virtual] bool QFile::setPermissions(QFileDevice::Permissions permissions)

Переопределяет: QFileDevice::setPermissions(QFileDevice::Permissions permissions).

Устанавливает права доступа для файла на заданные permissions. Возвращает true при успешном выполнении или false, если права не могут быть изменены.

Предупреждение: Эта функция не манипулирует ACL, что может ограничить её эффективность.

См. также permissions() и setFileName().

[static] bool QFile::setPermissions(const QString &fileName, QFileDevice::Permissions permissions)

Это перегруженный метод.

Устанавливает права доступа для файла fileName на permissions.

[override virtual] qint64 QFile::size() const

Переопределяет: QFileDevice::size() const.

[static] QString QFile::symLinkTarget(const QString &fileName)

Возвращает абсолютный путь к файлу или каталогу, на который указывает символическая ссылка (или ярлык в Windows), заданный fileName, или возвращает пустую строку, если fileName не соответствует символической ссылке.

Это имя может не соответствовать существующему файлу; это просто строка. QFile::exists() возвращает true, если символическая ссылка указывает на существующий файл.

Эта функция была добавлена в Qt 4.2.

QString QFile::symLinkTarget() const

Это перегруженный метод.

Возвращает абсолютный путь к файлу или каталогу, на который указывает символическая ссылка, или пустую строку, если объект не является символической ссылкой.

Это имя может не соответствовать существующему файлу; это просто строка. QFile::exists() возвращает true, если символическая ссылка указывает на существующий файл.

Эта функция была добавлена в Qt 4.2.

См. также fileName() и setFileName().