Класс 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.

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

Если копируемый файл является символической ссылкой (symlink), копируется файл, на который она ссылается, а не сама ссылка. За исключением прав доступа, которые копируются, никакие другие метаданные файла не копируются.

Возвращает 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.

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

Если копируемый файл является символической ссылкой (symlink), копируется файл, на который она ссылается, а не сама ссылка. За исключением прав доступа, которые копируются, никакие другие метаданные файла не копируются.

Возвращает 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.

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.

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

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

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

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

Перемещает файл, указанный в fileName(), в корзину. Возвращает true при успехе и устанавливает 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.

См. также 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() фактически не закрывает файл, а только сбрасывает его.

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

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

Реализует: QFileDevice::permissions() const.

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

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

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

Возвращает полное объединение битов QFile::Permission для 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 больше текущего размера fileName, новые байты будут заполнены нулями; если 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 в случае невозможности изменения разрешений.

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

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

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

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

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