Класс QFile

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

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

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

Типы public

Функции public

Реализованные функции public

• 18 функций public, унаследованных от QFileDevice
• 44 функций public, унаследованных от QIODevice
• 32 функций public, унаследованных от QObject

Статические члены public

• 10 статических public членов, унаследованных от QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 1 public slot, унаследованный от QObject
• 6 сигналов, унаследованных от QIODevice
• 2 сигнала, унаследованных от QObject
• 3 защищенных функций, унаследованных от QFileDevice
• 5 защищенных функций, унаследованных от QIODevice
• 9 защищенных функций, унаследованных от QObject

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

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

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

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

typedef QFile::DecoderFn

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

QString myDecoderFunc(const QByteArray &localFileName);

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

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

QFile::QFile()

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

QFile::QFile(const QString &name)

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

QFile::QFile(QObject *parent)

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

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

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

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

Возвращает имя, установленное с помощью 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().

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

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

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

Устанавливает права доступа к файлу в соответствии со спецификацией 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().

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

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

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

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

QString QFile::symLinkTarget() const

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

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

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

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

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