Класс 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. По умолчанию предполагается, что файл закодирован в UTF-8. Это можно изменить с помощью метода QTextStream::setEncoding().

Для записи текста можно использовать оператор<<(), перегруженный для работы с 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.

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

[since 6.0] QFile::QFile(const std::filesystem::path &name, QObject *parent)

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

Данная функция была добавлена в Qt 6.0.

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

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

QFile::QFile(QObject *parent)

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

[since 6.0] QFile::QFile(const std::filesystem::path &name)

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

Данная функция была добавлена в Qt 6.0.

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().

[since 6.0] bool QFile::copy(const std::filesystem::path &newName)

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

Данная функция была добавлена в Qt 6.0.

[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().

[since 6.0] std::filesystem::path QFile::filesystemFileName() const

Возвращает fileName() в формате std::filesystem::path.

Данная функция была добавлена в Qt 6.0.

bool QFile::link(const QString &linkName)

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

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

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

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

[since 6.0] bool QFile::link(const std::filesystem::path &newName)

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

Данная функция была добавлена в Qt 6.0.

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

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

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

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

[since 5.15] bool QFile::moveToTrash()

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

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

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

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

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

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

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

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

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

Реализует: QIODevice::open(QIODeviceBase::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, QIODeviceBase::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, QIODeviceBase::OpenMode mode, QFileDevice::FileHandleFlags handleFlags = DontCloseHandle)

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

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

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

Предупреждение: Если 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)

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

Возвращает полное значение, полученное путём побитового ИЛИ, разрешений для fileName.

[static, since 6.0] QFileDevice::Permissions QFile::permissions(const std::filesystem::path &filename)

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

Данная функция была добавлена в Qt 6.0.

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().

[since 6.0] bool QFile::rename(const std::filesystem::path &newName)

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

Данная функция была добавлена в Qt 6.0.

[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.

[since 6.0] void QFile::setFileName(const std::filesystem::path &name)

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

Этот метод был добавлен в Qt 6.0.

[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.

[static, since 6.0] bool QFile::setPermissions(const std::filesystem::path &filename, QFileDevice::Permissions permissionSpec)

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

Этот метод был добавлен в Qt 6.0.

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

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

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

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

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

QString QFile::symLinkTarget() const

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

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

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

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