Класс QFile

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

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

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

Типы

Открытые функции

Переопределённые открытые функции

• 16 открытых функций унаследовано от QFileDevice
• 33 открытых функции унаследовано от QIODevice
• 31 открытых функции унаследовано от QObject

Статические открытые члены

• 11 статических открытых членов унаследовано от QObject

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

• 1 свойство унаследовано от QObject
• 1 открытый слот унаследован от QObject
• 4 сигнала унаследованы от 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

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

QString myDecoderFunc(const QByteArray &localFileName);

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

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

QFile::QFile(const QString &name)

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

QFile::QFile(QObject *parent)

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

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

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

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

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

[virtual] bool QFile::open(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, OpenMode mode, 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 CE вы можете не иметь возможности вызвать resize().

Примечание для платформы Windows

fh должен быть открыт в двоичном режиме (т.е. строка режима должна содержать 'b', как в "rb" или "wb"), при доступе к файлам и другим устройствам с произвольным доступом. Qt будет переводить символы конца строки, если вы передадите QIODevice::Text в mode. Последовательные устройства, такие как stdin и stdout, не подвержены этому ограничению.

Вам необходимо включить поддержку консольных приложений для использования потоков stdin, stdout и stderr в консоли. Для этого добавьте следующее объявление в файл проекта вашего приложения:

CONFIG += console

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

bool QFile::open(int fd, OpenMode mode, 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().

Предупреждение: Для Windows CE вы можете не иметь возможности вызвать seek(), а size() возвращает 0.

Предупреждение: Поскольку эта функция открывает файл без указания имени файла, вы не можете использовать этот QFile с QFileInfo.

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

Права доступа[virtual] Permissions QFile::permissions() const

Реализовано как переопределение QFileDevice::permissions().

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

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

[virtual] bool QFile::resize(qint64 sz)

Реализовано как переопределение QFileDevice::resize().

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

[virtual] bool QFile::setPermissions(Permissions permissions)

Реализовано как переопределение QFileDevice::setPermissions().

Устанавливает права доступа к файлу в соответствии с permissions. Возвращает true при успешном выполнении или false, если права доступа не могут быть изменены.

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

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

[static] bool QFile::setPermissions(const QString &fileName, Permissions permissions)

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

Устанавливает права доступа для файла fileName в соответствии с permissions.

[virtual] qint64 QFile::size() const

Реализовано как переопределение QIODevice::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().