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

Открывает файл с помощью 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, 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)

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

Возвращает полную совокупность 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 &староеИмя, const QString &новоеИмя)

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

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

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

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

[override virtual] bool QFile::resize(qint64 размер)

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

[static] bool QFile::resize(const QString &имяФайла, qint64 размер)

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

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

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

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

void QFile::setFileName(const QString &имя)

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

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

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

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

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

[override virtual] bool QFile::setPermissions(QFileDevice::Permissions разрешения)

Переопределяет: QFileDevice::setPermissions(QFileDevice::Permissions разрешения).

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

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

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

[static] bool QFile::setPermissions(const QString &имяФайла, QFileDevice::Permissions разрешения)

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

Устанавливает разрешения для файла имяФайла на разрешения.

[static, since 6.0] bool QFile::setPermissions(const std::filesystem::path &имяФайла, QFileDevice::Permissions разрешения)

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

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

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

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

[static] QString QFile::symLinkTarget(const QString &имяФайла)

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

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

QString QFile::symLinkTarget() const

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

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

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

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