Класс QFile

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

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

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

Типы

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

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

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

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

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

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

• 1 свойство унаследованное от QObject
• 1 открытый слот унаследованный от 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 установит только флаг legacy read-only, и только в том случае, если ни один из флагов 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.

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

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

Предупреждение: Поскольку эта функция открывает файл без указания имени файла, вы не можете использовать этот 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().