Класс QFileInfo

Класс QFileInfo предоставляет информацию о файле, не зависящую от операционной системы. Подробнее...

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

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

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

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

Связанные внешние члены

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

Класс QFileInfo предоставляет информацию о файле, не зависящую от операционной системы.

QFileInfo предоставляет информацию об имени файла и его расположении (пути) в файловой системе, его правах доступа и о том, является ли он директорией или символической ссылкой и т.д. Также доступны размер файла и время последнего изменения/чтения. QFileInfo может также использоваться для получения информации о ресурсе Qt resource.

Объект QFileInfo может указывать на файл с относительным или абсолютным путем к файлу. Абсолютные пути к файлам начинаются с разделителя каталога "/" (или с указания диска в Windows). Относительные имена файлов начинаются с имени каталога или имени файла и указывают путь относительно текущего рабочего каталога. Пример абсолютного пути — строка "/tmp/quartz". Относительный путь может выглядеть как "src/fatlib". Вы можете использовать функцию isRelative() для проверки, использует ли QFileInfo относительный или абсолютный путь к файлу. Вы можете вызвать функцию makeAbsolute() для преобразования относительного пути QFileInfo в абсолютный.

Файл, с которым работает QFileInfo, устанавливается в конструкторе или позже с помощью setFile(). Используйте exists() для проверки существования файла и size() для получения его размера.

Тип файла определяется с помощью isFile(), isDir() и isSymLink(). Функция symLinkTarget() возвращает имя файла, на который указывает символическая ссылка.

В Unix (включая macOS и iOS) размер символической ссылки такой же, как и размер файла, на который она указывает, так как Unix обрабатывает символические ссылки прозрачно; аналогично, открытие символической ссылки с помощью QFile фактически открывает целевой файл ссылки. Например:

#ifdef Q_OS_UNIX

QFileInfo info1("/home/bob/bin/untabify");
info1.isSymLink();          // returns true
info1.absoluteFilePath();   // returns "/home/bob/bin/untabify"
info1.size();               // returns 56201
info1.symLinkTarget();      // returns "/opt/pretty++/bin/untabify"

QFileInfo info2(info1.symLinkTarget());
info2.isSymLink();          // returns false
info2.absoluteFilePath();   // returns "/opt/pretty++/bin/untabify"
info2.size();               // returns 56201

#endif

В Windows символические ссылки (ярлыки) являются .lnk файлами. Сообщаемый размер size() — это размер символической ссылки (а не целевого файла ссылки), а открытие символической ссылки с помощью QFile открывает .lnk файл. Например:

#ifdef Q_OS_WIN

QFileInfo info1("C:\\Documents and Settings\\Bob\\untabify.lnk");
info1.isSymLink();          // returns true
info1.absoluteFilePath();   // returns "C:/Documents and Settings/Bob/untabify.lnk"
info1.size();               // returns 743
info1.symLinkTarget();      // returns "C:/Pretty++/untabify"

QFileInfo info2(info1.symLinkTarget());
info2.isSymLink();          // returns false
info2.absoluteFilePath();   // returns "C:/Pretty++/untabify"
info2.size();               // returns 63942

#endif

Элементы имени файла можно извлечь с помощью path() и fileName(). Части имени файла, возвращаемые fileName(), можно извлечь с помощью baseName(), suffix() или completeSuffix(). Объекты QFileInfo, созданные классами Qt для каталогов, не будут содержать конечного разделителя файла. Если вы хотите использовать конечные разделители в собственных объектах QFileInfo, просто добавьте один к имени файла, переданному в конструкторы или setFile().

Даты файла возвращаются функциями created(), lastModified() и lastRead(). Информация о правах доступа к файлу получается с помощью isReadable(), isWritable() и isExecutable(). Владелец файла доступен из owner(), ownerId(), group() и groupId(). Вы можете проверить права доступа и владение файла в одной инструкции с помощью функции permission().

Примечание: В файловых системах NTFS проверка владения и прав доступа по умолчанию отключена по соображениям производительности. Чтобы включить её, добавьте следующую строку:

extern Q_CORE_EXPORT int qt_ntfs_permission_lookup;

Затем проверка прав доступа включается и отключается путем увеличения и уменьшения значения qt_ntfs_permission_lookup на 1.

qt_ntfs_permission_lookup++; // turn checking on
qt_ntfs_permission_lookup--; // turn it off again

Проблемы производительности

Некоторые функции QFileInfo запрашивают информацию о файле из файловой системы, но по соображениям производительности некоторые функции работают только с самим именем файла. Например: чтобы вернуть абсолютный путь к относительному имени файла, функция absolutePath() должна обратиться к файловой системе. Функция path(), однако, может работать напрямую с именем файла, поэтому она быстрее.

Примечание: Для повышения производительности QFileInfo кэширует информацию о файле.

Поскольку файлы могут изменяться другими пользователями или программами, а также другими частями той же программы, есть функция, которая обновляет информацию о файле: refresh(). Если вы хотите отключить кэширование QFileInfo и каждый раз обращаться к файловой системе при запросе информации, вызовите setCaching(false).

См. также QDir и QFile.

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

QFileInfo::QFileInfo()

Создаёт пустой объект QFileInfo.

Обратите внимание, что пустой объект QFileInfo не содержит ссылки на файл.

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

QFileInfo::QFileInfo(const QString &file)

Создаёт новый объект QFileInfo, содержащий информацию о заданном файле. file может также содержать абсолютный или относительный путь.

См. также setFile(), isRelative(), QDir::setCurrent() и QDir::isRelativePath().

QFileInfo::QFileInfo(const QFile &file)

Создаёт новый объект QFileInfo, содержащий информацию о файле file.

Если у file относительный путь, у QFileInfo также будет относительный путь.

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

QFileInfo::QFileInfo(const QDir &dir, const QString &file)

Создаёт новый объект QFileInfo, содержащий информацию о заданном файле file в каталоге dir.

Если у dir относительный путь, у QFileInfo также будет относительный путь.

Если file — абсолютный путь, то каталог, указанный dir, будет проигнорирован.

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

QFileInfo::QFileInfo(const QFileInfo &fileinfo)

Создаёт новый объект QFileInfo, являющийся копией заданного fileinfo.

QFileInfo::~QFileInfo()

Удаляет объект QFileInfo и освобождает его ресурсы.

QDir QFileInfo::absoluteDir() const

Возвращает абсолютный путь к файлу как объект QDir.

См. также dir(), filePath(), fileName() и isRelative().

QString QFileInfo::absoluteFilePath() const

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

Абсолютный путь состоит из полного пути и имени файла. В Unix он всегда начинается с корневого каталога '/'. В Windows он всегда начинается с 'D:/', где D — буква диска, за исключением сетевых общих ресурсов, не сопоставленных с буквой диска, в этом случае путь будет начинаться с '//sharename/'. QFileInfo преобразует буквы дисков в верхний регистр. Обратите внимание, что QDir этого не делает. Приведённый ниже фрагмент кода демонстрирует это.

    QFileInfo fi("c:/temp/foo"); => fi.absoluteFilePath() => "C:/temp/foo"

Эта функция возвращает то же значение, что и filePath(), если isRelative() равно true. В отличие от canonicalFilePath(), символические ссылки или избыточные элементы "." или ".." не обязательно удаляются.

Предупреждение: Если filePath() пусто, поведение этой функции не определено.

См. также filePath(), canonicalFilePath() и isRelative().

QString QFileInfo::absolutePath() const

Возвращает абсолютный путь к файлу. Он не включает имя файла.

В Unix абсолютный путь всегда начинается с корневого каталога '/'. В Windows он всегда начинается с 'D:/', где D — буква диска, за исключением сетевых общих ресурсов, не сопоставленных с буквой диска, в этом случае путь будет начинаться с '//sharename/'.

В отличие от canonicalPath(), символические ссылки или избыточные элементы "." или ".." не обязательно удаляются.

Предупреждение: Если filePath() пусто, поведение этой функции не определено.

См. также absoluteFilePath(), path(), canonicalPath(), fileName() и isRelative().

QString QFileInfo::baseName() const

Возвращает имя файла без пути.

Имя файла состоит из всех символов в имени файла до (но не включая) первого символа '.'.

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
QString base = fi.baseName();  // base = "archive"

Имя файла вычисляется одинаково на всех платформах, независимо от соглашений об именах файлов (например, ".bashrc" в Unix имеет пустое имя файла, и расширение — "bashrc").

См. также fileName(), suffix(), completeSuffix() и completeBaseName().

QString QFileInfo::bundleName() const

Возвращает имя пакета.

В macOS и iOS это возвращает соответствующее локализованное имя пакета, если путь isBundle(). На всех остальных платформах возвращается пустая строка.

Пример:

QFileInfo fi("/Applications/Safari.app");
QString bundle = fi.bundleName();                // name = "Safari"

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

См. также isBundle(), filePath(), baseName() и suffix().

bool QFileInfo::caching() const

Возвращает true если кэширование включено, иначе возвращает false.

См. также setCaching() и refresh().

QString QFileInfo::canonicalFilePath() const

Возвращает канонический путь, включая имя файла, т.е. абсолютный путь без символических ссылок или избыточных элементов «.» или «..».

Если файл не существует, canonicalFilePath() возвращает пустую строку.

См. также filePath(), absoluteFilePath() и dir().

QString QFileInfo::canonicalPath() const

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

Если файл не существует, canonicalPath() возвращает пустую строку.

См. также path() и absolutePath().

QString QFileInfo::completeBaseName() const

Возвращает полное имя базы файла без пути.

Полное имя базы состоит из всех символов в имени файла до (но не включая) последнего символа «.».

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
QString base = fi.completeBaseName();  // base = "archive.tar"

См. также fileName(), suffix(), completeSuffix() и baseName().

QString QFileInfo::completeSuffix() const

Возвращает полное расширение (расширение) файла.

Полное расширение состоит из всех символов в имени файла после (но не включая) первого символа «.».

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
QString ext = fi.completeSuffix();  // ext = "tar.gz"

См. также fileName(), suffix(), baseName() и completeBaseName().

QDateTime QFileInfo::created() const

Возвращает дату и местное время создания файла.

На большинстве Unix-систем эта функция возвращает время последнего изменения статуса. Изменение статуса происходит при создании файла, а также всякий раз, когда пользователь записывает или устанавливает информацию об узле (например, изменяет права доступа к файлу).

Если время создания или время последнего изменения статуса недоступны, возвращается то же значение, что и lastModified().

См. также lastModified() и lastRead().

QDir QFileInfo::dir() const

Возвращает путь к родительскому каталогу объекта в виде объекта QDir.

Примечание: Возвращаемый объект QDir всегда соответствует родительскому каталогу объекта, даже если QFileInfo представляет собой каталог.

Для каждого из следующих случаев dir() возвращает QDir "~/examples/191697".

    QFileInfo fileInfo1("~/examples/191697/.");
    QFileInfo fileInfo2("~/examples/191697/..");
    QFileInfo fileInfo3("~/examples/191697/main.cpp");

Для каждого из следующих случаев dir() возвращает QDir ".".

    QFileInfo fileInfo4(".");
    QFileInfo fileInfo5("..");
    QFileInfo fileInfo6("main.cpp");

См. также absolutePath(), filePath(), fileName(), isRelative() и absoluteDir().

bool QFileInfo::exists() const

Возвращает true, если файл существует; в противном случае возвращает false.

Примечание: Если файл является символической ссылкой, которая указывает на несуществующий файл, возвращается false.

[static] bool QFileInfo::exists(const QString &file)

Возвращает true, если файл file существует; в противном случае возвращает false.

Примечание: Если file является символической ссылкой, указывающей на несуществующий файл, возвращается false.

Примечание: Использование этой функции быстрее, чем использование QFileInfo(file).exists() для доступа к файловой системе.

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

QString QFileInfo::fileName() const

Возвращает имя файла без пути.

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
QString name = fi.fileName();                // name = "archive.tar.gz"

Обратите внимание, что если этому объекту QFileInfo задан путь, оканчивающийся на слеш, имя файла считается пустым.

См. также isRelative(), filePath(), baseName() и suffix().

QString QFileInfo::filePath() const

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

См. также absoluteFilePath(), canonicalFilePath() и isRelative().

QString QFileInfo::group() const

Возвращает группу файла. В Windows, на системах, где у файлов нет групп, или если произошла ошибка, возвращается пустая строка.

Эта функция может быть ресурсоемкой на Unix (порядка миллисекунд).

См. также groupId(), owner() и ownerId().

uint QFileInfo::groupId() const

Возвращает идентификатор группы, к которой принадлежит файл.

В Windows и на системах, где у файлов нет групп, эта функция всегда возвращает (uint) -2.

См. также group(), owner() и ownerId().

bool QFileInfo::isAbsolute() const

Возвращает true, если имя пути файла абсолютное, в противном случае возвращает false, если путь относительный.

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

bool QFileInfo::isBundle() const

Возвращает true, если этот объект указывает на пакет или на символическую ссылку на пакет на macOS и iOS; в противном случае возвращает false.

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

См. также isDir(), isSymLink() и isFile().

bool QFileInfo::isDir() const

Возвращает true, если этот объект указывает на каталог или на символическую ссылку на каталог; в противном случае возвращает false.

См. также isFile(), isSymLink() и isBundle().

bool QFileInfo::isExecutable() const

Возвращает true, если файл исполняемый; в противном случае возвращает false.

См. также isReadable(), isWritable() и permission().

bool QFileInfo::isFile() const

Возвращает true, если этот объект указывает на файл или на символическую ссылку на файл. Возвращает false, если объект указывает на что-то, что не является файлом, например, на каталог.

См. также isDir(), isSymLink() и isBundle().

bool QFileInfo::isHidden() const

Возвращает true, если это «скрытый» файл; в противном случае возвращает false.

Примечание: Эта функция возвращает true для специальных записей «.» и «..» на Unix, хотя QDir::entryList рассматривает их как показано.

bool QFileInfo::isNativePath() const

Возвращает true, если путь к файлу может быть использован напрямую с нативными API. Возвращает false, если файл в противном случае поддерживается виртуальной файловой системой внутри Qt, например, системой ресурсов Qt.

Примечание: Нативные пути могут по-прежнему потребовать преобразования разделителей пути и кодировки символов в зависимости от платформы и требований к входным данным нативного API.

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

См. также QDir::toNativeSeparators(), QFile::encodeName(), filePath(), absoluteFilePath() и canonicalFilePath().

bool QFileInfo::isReadable() const

Возвращает true, если пользователь может читать файл; в противном случае возвращает false.

Примечание: Если проверка разрешений NTFS не включена, результат в Windows будет отражать только существование файла.

См. также isWritable(), isExecutable() и permission().

bool QFileInfo::isRelative() const

Возвращает true, если имя пути файла относительное, в противном случае возвращает false, если путь абсолютный (например, в Unix путь абсолютный, если он начинается с «/»).

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

bool QFileInfo::isRoot() const

Возвращает true, если объект указывает на каталог или символическую ссылку на каталог, и этот каталог является корневым каталогом; в противном случае возвращает false.

bool QFileInfo::isSymLink() const

Возвращает true, если этот объект указывает на символическую ссылку; в противном случае возвращает false.

Символические ссылки существуют в Unix (включая macOS и iOS) и Windows и обычно создаются с помощью команд ln -s или mklink соответственно. Открытие символической ссылки фактически открывает цель ссылки.

Кроме того, для ярлыков (*.lnk файлы) в Windows будет возвращено значение true. Открытие таких ярлыков откроет сам .lnk файл.

Пример:

QFileInfo info(fileName);
if (info.isSymLink())
    fileName = info.symLinkTarget();

Примечание: Если символическая ссылка указывает на несуществующий файл, exists() возвращает false.

См. также isFile(), isDir() и symLinkTarget().

bool QFileInfo::isWritable() const

Возвращает true, если пользователь может записывать в файл; в противном случае возвращает false.

Примечание: Если проверка NTFS-разрешений не включена, результат в Windows просто отразит, помечен ли файл как только для чтения.

См. также isReadable(), isExecutable() и permission().

QDateTime QFileInfo::lastModified() const

Возвращает дату и локальное время последнего изменения файла.

См. также created() и lastRead().

QDateTime QFileInfo::lastRead() const

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

На платформах, где эта информация недоступна, возвращает то же, что и lastModified().

См. также created() и lastModified().

bool QFileInfo::makeAbsolute()

Преобразует путь к файлу в абсолютный путь, если он им не является. Возвращает true для указания того, что путь был преобразован; в противном случае возвращает false для указания того, что путь уже был абсолютным.

См. также filePath() и isRelative().

QString QFileInfo::owner() const

Возвращает владельца файла. На системах, где у файлов нет владельцев, или если произошла ошибка, возвращается пустая строка.

Эта функция может быть длительной на Unix (в порядке миллисекунд). В Windows она вернёт пустую строку, если не включена проверка NTFS-разрешений.

См. также ownerId(), group() и groupId().

uint QFileInfo::ownerId() const

Возвращает идентификатор владельца файла.

В Windows и на системах, где у файлов нет владельцев, эта функция возвращает ((uint) -2).

См. также owner(), group() и groupId().

QString QFileInfo::path() const

Возвращает путь к файлу. Он не включает имя файла.

Обратите внимание, что если данному объекту QFileInfo задан путь, заканчивающийся слешем, имя файла считается пустым, и эта функция вернёт весь путь.

См. также filePath(), absolutePath(), canonicalPath(), dir(), fileName() и isRelative().

bool QFileInfo::permission(QFile::Permissions permissions) const

Проверяет разрешения файла. Аргумент permissions может быть несколькими флагами типа QFile::Permissions, объединёнными операцией ИЛИ, для проверки комбинаций разрешений.

На системах, где у файлов нет разрешений, эта функция всегда возвращает true.

Примечание: Результат может быть неточным в Windows, если проверка NTFS-разрешений не включена.

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
if (fi.permission(QFile::WriteUser | QFile::ReadGroup))
    qWarning("I can change the file; my group can read the file");
if (fi.permission(QFile::WriteGroup | QFile::WriteOther))
    qWarning("The group or others can change the file");

См. также isReadable(), isWritable() и isExecutable().

QFile::Permissions QFileInfo::permissions() const

Возвращает полную комбинацию QFile::Permissions, объединённых операцией ИЛИ, для файла.

Примечание: Результат может быть неточным в Windows, если проверка NTFS-разрешений не включена.

void QFileInfo::refresh()

Обновляет информацию о файле, то есть считывает информацию из файловой системы при следующем получении кэшированного свойства.

void QFileInfo::setCaching(bool enable)

Если enable равно true, включает кэширование информации о файле. Если enable равно false, кэширование отключено.

При включённом кэшировании QFileInfo считывает информацию о файле из файловой системы только при первом обращении, но обычно не позднее.

Кэширование включено по умолчанию.

См. также refresh() и caching().

void QFileInfo::setFile(const QString &file)

Устанавливает файл, о котором QFileInfo предоставляет информацию, на file.

file может также содержать абсолютный или относительный путь к файлу. Абсолютные пути начинаются с разделителя каталогов (например, "/" в Unix) или спецификации диска (в Windows). Относительные имена файлов начинаются с имени каталога или имени файла и указывают путь относительно текущего каталога.

Пример:

QString absolute = "/local/bin";
QString relative = "local/bin";
QFileInfo absFile(absolute);
QFileInfo relFile(relative);

QDir::setCurrent(QDir::rootPath());
// absFile and relFile now point to the same file

QDir::setCurrent("/tmp");
// absFile now points to "/local/bin",
// while relFile points to "/tmp/local/bin"

См. также isFile(), isRelative(), QDir::setCurrent() и QDir::isRelativePath().

void QFileInfo::setFile(const QFile &file)

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

Устанавливает файл, о котором QFileInfo предоставляет информацию, на file.

Если file содержит относительный путь, у QFileInfo также будет относительный путь.

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

void QFileInfo::setFile(const QDir &dir, const QString &file)

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

Устанавливает файл, о котором QFileInfo предоставляет информацию, на file в каталоге dir.

Если file содержит относительный путь, у QFileInfo также будет относительный путь.

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

qint64 QFileInfo::size() const

Возвращает размер файла в байтах. Если файл не существует или не может быть получен, возвращается 0.

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

QString QFileInfo::suffix() const

Возвращает суффикс (расширение) файла.

Суффикс состоит из всех символов в имени файла после (но не включая) последней точки.

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
QString ext = fi.suffix();  // ext = "gz"

Суффикс файла вычисляется одинаково на всех платформах, независимо от соглашений об именах файлов (например, ".bashrc" в Unix имеет пустое имя файла, и суффикс — "bashrc").

См. также fileName(), completeSuffix(), baseName() и completeBaseName().

void QFileInfo::swap(QFileInfo &other)

Обменивается информацией о файле с other. Эта функция очень быстрая и никогда не терпит неудачи.

Эта функция была представлена в Qt 5.0.

QString QFileInfo::symLinkTarget() const

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

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

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

См. также exists(), isSymLink(), isDir() и isFile().

bool QFileInfo::operator!=(const QFileInfo &fileinfo) const

Возвращает true если этот объект QFileInfo ссылается на другой файл, чем тот, который указан в fileinfo; в противном случае возвращает false.

См. также operator==().

QFileInfo &QFileInfo::operator=(const QFileInfo &fileinfo)

Создаёт копию заданного fileinfo и присваивает её этому QFileInfo.

QFileInfo &QFileInfo::operator=(QFileInfo &&other)

Перемещает присваивание other этому экземпляру QFileInfo.

Эта функция была представлена в Qt 5.2.

bool QFileInfo::operator==(const QFileInfo &fileinfo) const

Возвращает true , если этот объект QFileInfo ссылается на файл в том же расположении, что и fileinfo; в противном случае возвращает false.

Обратите внимание, что результат сравнения двух пустых объектов QFileInfo, не содержащих ссылок на файлы (пути к файлам, которые не существуют или пустые), не определен.

Предупреждение: Это не сравнит два разных символических ссылки, указывающие на один и тот же файл.

Предупреждение: Длинные и короткие имена файлов, которые ссылаются на один и тот же файл в Windows, обрабатываются так, как если бы они ссылались на разные файлы.

См. также operator!=().