Класс 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, если этот объект указывает на символическую ссылку (или на ярлык в Windows); в противном случае возвращает false.

В Unix (включая macOS и iOS), открытие символической ссылки фактически открывает целевой объект ссылки. В Windows это открывает .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()

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

Примечание: В Windows CE может быть задержка для драйвера файловой системы в обнаружении изменений файла.

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

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

Это имя может не представлять существующий файл; это только строка. 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!=().