Класс 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 бит. Если вы хотите использовать стандартные API C++ (<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. Она может быть полезна для флэш-накопителей, использующих файловые системы VFAT. Также не обрабатываются POSIX ACL.

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

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

typedef QFile::DecoderFn

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

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 бит, определяемую локальными настройками пользователя. Этого достаточно для имён файлов, выбираемых пользователем. Имена файлов, жёстко заданные в приложении, должны использовать только символы ASCII 7-битной кодировки.

См. также 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().

bool QFile::moveToTrash()

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

Примечание: В системах, где системный API не сообщает местоположение файла в корзине, fileName() будет установлено в пустую строку после перемещения файла. В системах без корзины эта функция всегда возвращает false.

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

[static] bool QFile::moveToTrash(const QString &fileName, QString *pathInTrash = nullptr)

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

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

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

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

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

Реализует: QIODevice::open(QIODevice::OpenMode mode).

Открывает файл с использованием режима OpenMode 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)

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

Возвращает полную комбинацию 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 больше текущего размера файла, новые байты будут заполнены нулями; если 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

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

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

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

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