QFileInfo Class

Detailed Description

QFileInfo provides information about a file system entry, such as its name, path, access rights and whether it is a regular file, directory or symbolic link. The entry's size and last modified/read times are also available. QFileInfo can also be used to obtain information about a Qt resource.

A QFileInfo can point to a file system entry with either an absolute or a relative path:

  • On Unix, absolute paths begin with the directory separator '/'. On Windows, absolute paths begin with a drive specification (for example, D:/).

  • Relative paths begin with a directory name or a regular file name and specify a file system entry's path relative to the current working directory.

An example of an absolute path is the string "/tmp/quartz". A relative path may look like "src/fatlib". You can use the function isRelative() to check whether a QFileInfo is using a relative or an absolute path. You can call the function makeAbsolute() to convert a relative QFileInfo's path to an absolute path.

Paths starting with a colon (:) are always considered absolute, as they denote a QResource. The file system entry path that the QFileInfo works on is set in the constructor or later with setFile(). Use exists() to see if the entry actually exists and size() to get its size.

The file system entry's type is obtained with isFile(), isDir(), and isSymLink(). The symLinkTarget() function provides the absolute path of the target the symlink points to.

The path elements of the file system entry can be extracted with path() and fileName(). The fileName()'s parts can be extracted with baseName(), suffix(), or completeSuffix(). QFileInfo objects referring to directories created by Qt classes will not have a trailing directory separator '/'. If you wish to use trailing separators in your own file info objects, just append one to the entry's path given to the constructors or setFile().

Date and time related information are returned by birthTime(), fileTime(), lastModified(), lastRead(), and metadataChangeTime(). Information about access permissions can be obtained with isReadable(), isWritable(), and isExecutable(). Ownership information can be obtained with owner(), ownerId(), group(), and groupId(). You can also examine permissions and ownership in a single statement using the permission() function.

Symbolic Links and Shortcuts

 
Sélectionnez
#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

On Windows, shortcuts (.lnk files) are currently treated as symlinks. As on Unix systems, the property getters return the size of the target, not the .lnk file itself. This behavior is deprecated and will likely be removed in a future version of Qt, after which .lnk files will be treated as regular files.

 
Sélectionnez
#ifdef Q_OS_WIN

QFileInfo info1("C:\\Users\\Bob\\untabify.lnk");
info1.isSymLink();          // returns true
info1.absoluteFilePath();   // returns "C:/Users/Bob/untabify.lnk"
info1.size();               // returns 63942
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

NTFS permissions

On NTFS file systems, ownership and permissions checking is disabled by default for performance reasons. To enable it, include the following line:

 
Sélectionnez
extern Q_CORE_EXPORT int qt_ntfs_permission_lookup;

Permission checking is then turned on and off by incrementing and decrementing qt_ntfs_permission_lookup by 1.

 
Sélectionnez
qt_ntfs_permission_lookup++; // turn checking on
qt_ntfs_permission_lookup--; // turn it off again

Since this is a non-atomic global variable, it is only safe to increment or decrement qt_ntfs_permission_lookup before any threads other than the main thread have started or after every thread other than the main thread has ended.

From Qt 6.6 the variable qt_ntfs_permission_lookup is deprecated. Please use the following alternatives.

The safe and easy way to manage permission checks is to use the RAII class QNtfsPermissionCheckGuard.

 
Sélectionnez
void complexFunction()
{
    QNtfsPermissionCheckGuard permissionGuard;  // check is enabled

    // do complex things here that need permission check enabled

}   // as the guard goes out of scope the check is disabled

If you need more fine-grained control, it is possible to manage the permission with the following functions instead:

 
Sélectionnez
qAreNtfsPermissionChecksEnabled();   // check status
qEnableNtfsPermissionChecks();       // turn checking on
qDisableNtfsPermissionChecks();      // turn it off again

Performance Considerations

Some of QFileInfo's functions have to query the file system, but for performance reasons, some functions only operate on the path string. For example: To return the absolute path of a relative entry's path, absolutePath() has to query the file system. The path() function, however, can work on the file name directly, and so it is faster.

QFileInfo also caches information about the file system entry it refers to. Because the file system can be changed by other users or programs, or even by other parts of the same program, there is a function that refreshes the information stored in QFileInfo, namely refresh(). To switch off a QFileInfo's caching (that is, force it to query the underlying file system every time you request information from it), call setCaching(false).

Fetching information from the file system is typically done by calling (possibly) expensive system functions, so QFileInfo (depending on the implementation) might not fetch all the information from the file system at construction. To make sure that all information is read from the file system immediately, use the stat() member function.

birthTime(), fileTime(), lastModified(), lastRead(), and metadataChangeTime() return times in local time by default. Since native file system API typically uses UTC, this requires a conversion. If you don't actually need the local time, you can avoid this by requesting the time in QTimeZone::UTC directly.

Platform Specific Issues

On Android, some limitations apply when dealing with content URIs:

See Also

See also QDir, QFile

Member Function Documentation

 

QFileInfo::QFileInfo()

Constructs an empty QFileInfo object that doesn't refer to any file system entry.

See Also

See also setFile()

[explicit] QFileInfo::QFileInfo(const QString &path)

Constructs a QFileInfo that gives information about a file system entry located at path that can be absolute or relative.

If path is relative, the QFileInfo will also have a relative path.

See Also

[explicit] QFileInfo::QFileInfo(const QFileDevice &file)

Constructs a new QFileInfo that gives information about file file.

If the file has a relative path, the QFileInfo will also have a relative path.

See Also

See also isRelative()

[explicit] QFileInfo::QFileInfo(const QDir &dir, const QString &path)

Constructs a new QFileInfo that gives information about the given file system entry path that is relative to the directory dir.

If dir has a relative path, the QFileInfo will also have a relative path.

If path is absolute, then the directory specified by dir will be disregarded.

See Also

See also isRelative()

[since 6.0] QFileInfo::QFileInfo(const std::filesystem::path &file)

Constructs a new QFileInfo that gives information about the given file.

This function was introduced in Qt 6.0.

See Also

[since 6.0] QFileInfo::QFileInfo(const QDir &dir, const std::filesystem::path &path)

Constructs a new QFileInfo that gives information about the file system entry at path that is relative to the directory dir.

If dir has a relative path, the QFileInfo will also have a relative path.

If path is absolute, then the directory specified by dir will be disregarded.

This function was introduced in Qt 6.0.

QFileInfo::QFileInfo(const QFileInfo &fileinfo)

Constructs a new QFileInfo that is a copy of the given fileinfo.

QFileInfo::~QFileInfo()

Destroys the QFileInfo and frees its resources.

QDir QFileInfo::absoluteDir() const

Returns a QDir object representing the absolute path of the parent directory of the file system entry that this QFileInfo refers to.

 
Sélectionnez
// Given a current working directory of "/home/user/Documents/memos/"
QFileInfo info1(u"relativeFile"_s);
qDebug() << info1.absolutePath(); // "/home/user/Documents/memos/"
qDebug() << info1.baseName(); // "relativeFile"
qDebug() << info1.absoluteDir(); // QDir(u"/home/user/Documents/memos"_s)
qDebug() << info1.absoluteDir().path(); // "/home/user/Documents/memos"

// A QFileInfo on a dir
QFileInfo info2(u"/home/user/Documents/memos"_s);
qDebug() << info2.absolutePath(); // "/home/user/Documents"
qDebug() << info2.baseName(); // "memos"
qDebug() << info2.absoluteDir(); // QDir(u"/home/user/Documents"_s)
qDebug() << info2.absoluteDir().path(); // "/home/user/Documents"
See Also

See also dir(), filePath(), fileName(), isRelative()

QString QFileInfo::absoluteFilePath() const

Returns the absolute full path to the file system entry this QFileInfo refers to, including the entry's name.

On Unix, absolute paths begin with the directory separator '/'. On Windows, absolute paths begin with a drive specification (for example, D:/).

On Windows, the paths of network shares that are not mapped to a drive letter begin with //sharename/. QFileInfo will uppercase drive letters. Note that QDir does not do this. The code snippet below shows this.

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

This function returns the same as filePath(), unless isRelative() is true. In contrast to canonicalFilePath(), symbolic links or redundant "." or ".." elements are not necessarily removed.

If filePath() is empty the behavior of this function is undefined.

See Also

QString QFileInfo::absolutePath() const

Returns the absolute path of the file system entry this QFileInfo refers to, excluding the entry's name.

On Unix, absolute paths begin with the directory separator '/'. On Windows, absolute paths begin with a drive specification (for example, D:/).

On Windows, the paths of network shares that are not mapped to a drive letter begin with //sharename/.

In contrast to canonicalPath() symbolic links or redundant "." or ".." elements are not necessarily removed.

If filePath() is empty the behavior of this function is undefined.

See Also

QString QFileInfo::baseName() const

Returns the base name of the file without the path.

The base name consists of all characters in the file up to (but not including) the first '.' character.

Example:

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

The base name of a file is computed equally on all platforms, independent of file naming conventions (e.g., ".bashrc" on Unix has an empty base name, and the suffix is "bashrc").

See Also