Класс QFile

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

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

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

Типы Public

Public Функции

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

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

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

• 11 static public членов унаследованных от QObject

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

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

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

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

typedef QFile::DecoderFn

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

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

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

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

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

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

void QFile::setFileName(const QString &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().