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

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

[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, если символическая ссылка указывает на существующий файл.

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

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