QDir Class

The QDir class provides access to directory structures and their contents. More…

List of all members, including inherited members

Public Types

Public Functions

Static Public Members

Detailed Description

A QDir holds a directory path together with name filters, an entry filter and a sort order. Use it to list a directory, to create, remove and rename entries, and to convert between relative and absolute paths. Paths always use / as the separator.

A path that starts with a colon, such as :/icons, refers to a directory of resources. It can be listed, entered and iterated with QDirIterator like any other directory, but nothing can be created, removed or renamed in it.

setSearchPaths() gives a name prefix a list of directories, so that a path such as icons:open.png names the first such file in them.

QDir dir("/var/log");
dir.setNameFilters(QStringList() << "*.log");
const QStringList logs = dir.entryList(QDir::Files, QDir::Time);

See also QFileInfo and QStandardPaths.

Differences from Qt

Member Type Documentation

enum QDir::Filter

Selects which entries entryList() and entryInfoList() return.

See also filter() and setFilter().

typedef QDir::Filters

A QFlags of Filter values.

enum QDir::SortFlag

Selects the order of the entries returned by entryList() and entryInfoList().

See also sorting() and setSorting().

typedef QDir::SortFlags

A QFlags of SortFlag values.

Member Function Documentation

[explicit] QDir::QDir(const QString &path = QString())

Constructs a QDir for path. An empty path refers to the current directory (.).

See also setPath().

QDir::QDir(const QString &path, const QString &nameFilter, SortFlags sort = SortFlags(SortFlag(Name | IgnoreCase)), Filters filter = AllEntries)

Constructs a QDir for path that lists entries matching nameFilter, which holds patterns separated by spaces or semicolons, with the given sort order and filter.

See also setNameFilters(), setSorting() and setFilter().

QString QDir::absoluteFilePath(const QString &fileName) const

Returns fileName prefixed with the absolute path of the directory. If fileName is absolute, it is returned unchanged. The file does not have to exist.

See also filePath(), relativeFilePath() and absolutePath().

QString QDir::absolutePath() const

Returns the absolute path of the directory, with . and .. components resolved lexically. Symbolic links are not resolved.

See also canonicalPath(), path() and cleanPath().

[static] void QDir::addSearchPath(const QString &prefix, const QString &path)

Adds path to the end of the search paths for prefix.

This function was introduced in 4.3.

See also setSearchPaths().

QString QDir::canonicalPath() const

Returns the canonical path of the directory, with symbolic links resolved. Returns an empty string if the directory does not exist.

See also absolutePath() and QFileInfo::canonicalFilePath().

bool QDir::cd(const QString &dirName)

Changes the directory to dirName and returns true. Returns false, leaving the path unchanged, if dirName is not an existing directory. .. is resolved lexically.

See also cdUp() and setPath().

bool QDir::cdUp()

Changes to the parent directory. Returns true on success; otherwise returns false.

See also cd().

[static] QString QDir::cleanPath(const QString &path)

Returns path with redundant separators and . components removed, and .. components resolved lexically. A trailing slash is dropped. An empty path is returned as is; a path that cleans to nothing becomes .. A resource path is cleaned to one that starts with :/.

qsizetype QDir::count() const

Returns the number of entries that entryList() returns.

[static] QDir QDir::current()

Returns a QDir for the current working directory.

See also currentPath() and setCurrent().

[static] QString QDir::currentPath()

Returns the absolute path of the process's current working directory.

See also setCurrent() and current().

QString QDir::dirName() const

Returns the name of the directory, which is the last component of its cleaned path. Returns an empty string for the root directory.

See also path().

[static] QFileInfoList QDir::drives()

Returns the root directories of the system. On Nt this is always the list containing only /.

See also root().

QFileInfoList QDir::entryInfoList(Filters filters = NoFilter, SortFlags sort = NoSort) const

Returns a QFileInfo for each entry in the directory that matches the directory's name filters and the given filters, sorted by sort. If filters is NoFilter, the directory's own filter is used; if sort is NoSort, its own sort order is used.

See also entryList(), setNameFilters(), setFilter() and setSorting().

QFileInfoList QDir::entryInfoList(const QStringList &nameFilters, Filters filters = NoFilter, SortFlags sort = NoSort) const

This is an overloaded function.

Returns the entries that match nameFilters instead of the directory's own name filters.

QStringList QDir::entryList(Filters filters = NoFilter, SortFlags sort = NoSort) const

Returns the names of the entries in the directory that match the directory's name filters and the given filters, sorted by sort. If filters is NoFilter, the directory's own filter is used; if sort is NoSort, its own sort order is used.

See also entryInfoList(), setNameFilters(), setFilter() and setSorting().

QStringList QDir::entryList(const QStringList &nameFilters, Filters filters = NoFilter, SortFlags sort = NoSort) const

This is an overloaded function.

Returns the entries that match nameFilters instead of the directory's own name filters.

bool QDir::exists() const

Returns true if the directory exists; otherwise returns false.

See also isReadable().

bool QDir::exists(const QString &name) const

This is an overloaded function.

Returns true if the file or directory name, relative to the directory, exists; otherwise returns false.

QString QDir::filePath(const QString &fileName) const

Returns fileName prefixed with the path of the directory. If fileName is absolute, it is returned unchanged. The file does not have to exist.

See also absoluteFilePath() and relativeFilePath().

Filters QDir::filter() const

Returns the entry filter used by entryList() and entryInfoList().

See also setFilter().

[static] QString QDir::fromNativeSeparators(const QString &path)

Returns path unchanged; native paths already use / on Nt.

See also toNativeSeparators().

[static] QDir QDir::home()

Returns a QDir for the user's home directory.

See also homePath().

[static] QString QDir::homePath()

Returns the path of the user's home directory. It is taken from HOME, then from the password database, and falls back to the root directory.

See also home().

bool QDir::isAbsolute() const

Returns true if the directory's path is absolute; otherwise returns false.

See also isRelative() and makeAbsolute().

[static] bool QDir::isAbsolutePath(const QString &path)

Returns true if path is absolute, which means it starts with a slash, or with a colon for a resource; otherwise returns false.

See also isRelativePath().

bool QDir::isEmpty(Filters filters = Filters(Filter(AllEntries | NoDotAndDotDot))) const

Returns true if the directory contains no entries that pass filters, using the directory's name filters; otherwise returns false. The default filters ignore . and ...

See also entryList().

bool QDir::isReadable() const

Returns true if the directory exists and the process may list and enter it; otherwise returns false.

See also exists().

bool QDir::isRelative() const

Returns true if the directory's path is relative; otherwise returns false.

See also isAbsolute().

[static] bool QDir::isRelativePath(const QString &path)

Returns true if path is relative; otherwise returns false.

See also isAbsolutePath().

bool QDir::isRoot() const

Returns true if the directory is the root directory; otherwise returns false.

See also rootPath().

[static] QChar QDir::listSeparator()

Returns the separator used in path lists such as PATH, :.

See also separator().

bool QDir::makeAbsolute()

Converts the directory's path to an absolute path. Always returns true.

See also isAbsolute() and absolutePath().

[static] bool QDir::match(const QString &filter, const QString &fileName)

Returns true if fileName matches the wildcard patterns in filter, which are separated by spaces or semicolons; otherwise returns false. Matching is case-insensitive.

See also entryList().

[static] bool QDir::match(const QStringList &filters, const QString &fileName)

This is an overloaded function.

Returns true if fileName matches any of the wildcard patterns in filters; otherwise returns false. Matching is case-insensitive.

bool QDir::mkdir(const QString &dirName) const

Creates the sub-directory dirName and returns true on success. The parent must already exist.

See also mkpath() and rmdir().

bool QDir::mkpath(const QString &dirPath) const

Creates dirPath and any missing parent directories. Returns true if the directory exists afterwards; otherwise returns false.

See also mkdir() and rmpath().

QStringList QDir::nameFilters() const

Returns the name filters used by entryList() and entryInfoList(). The default is a single * pattern.

See also setNameFilters().

[static] QStringList QDir::nameFiltersFromString(const QString &nameFilter)

Returns the name filters in nameFilter, which separates them with spaces or semicolons. Leading and trailing spaces of each filter are removed and empty filters are skipped.

See also setNameFilters().

QString QDir::operator[](qsizetype i) const

Returns the file name at index i of entryList().

QString QDir::path() const

Returns the path of the directory, as set with setPath(). It may be relative.

See also absolutePath() and dirName().

void QDir::refresh() const

Does nothing. Entries are read from the file system on every call, so there is no cache to refresh.

QString QDir::relativeFilePath(const QString &fileName) const

Returns the path of fileName relative to the directory, using .. components where needed. Returns . if fileName is the directory itself.

See also filePath() and absoluteFilePath().

bool QDir::remove(const QString &fileName)

Removes the file fileName, relative to the directory. Returns true on success; otherwise returns false.

See also rename() and QFile::remove().

bool QDir::removeRecursively()

Removes the directory, including all its contents. Symbolic links are removed, not followed. Returns true on success; a directory that does not exist also counts as success.

See also rmdir().

bool QDir::rename(const QString &oldName, const QString &newName)

Renames the file or directory oldName to newName, both relative to the directory. Returns true on success; otherwise returns false.

See also remove() and QFile::rename().

bool QDir::rmdir(const QString &dirName) const

Removes the empty sub-directory dirName and returns true on success.

See also rmpath(), removeRecursively() and mkdir().

bool QDir::rmpath(const QString &dirPath) const

Removes the directory dirPath, then each parent directory that becomes empty. Returns true if dirPath itself was removed.

See also rmdir() and mkpath().

[static] QDir QDir::root()

Returns a QDir for the root directory.

See also rootPath().

[static] QString QDir::rootPath()

Returns the path of the root directory, /.

See also root() and isRoot().

[static] QStringList QDir::searchPaths(const QString &prefix)

Returns the search paths for prefix, or an empty list if it has none.

This function was introduced in 4.3.

See also setSearchPaths() and addSearchPath().

[static] QChar QDir::separator()

Returns the directory separator, /.

See also listSeparator().

[static] bool QDir::setCurrent(const QString &path)

Sets the process's current working directory to path. Returns true on success; otherwise returns false.

See also currentPath().

void QDir::setFilter(Filters filter)

Sets the entry filter used by entryList() and entryInfoList() to filter.

See also filter().

void QDir::setNameFilters(const QStringList &nameFilters)

Sets the name filters used by entryList() and entryInfoList() to nameFilters.

See also nameFilters().

void QDir::setPath(const QString &path)

Sets the path of the directory to path. Duplicate and trailing slashes are removed. The directory does not have to exist.

See also path() and absolutePath().

[static] void QDir::setSearchPaths(const QString &prefix, const QStringList &searchPaths)

Sets or replaces the search paths for file names that start with prefix to searchPaths. An empty list removes the prefix.

A file name such as icons:open.png is then looked up in each search path in turn, and refers to the first file that exists. If none exists, it refers to the file in the first search path, so that files can be created there. Search paths can be resource directories, such as :/icons, and can use other prefixes. QFile, QFileInfo, QDir and QDirIterator all resolve prefixes:

QDir::setSearchPaths("icons", QStringList() << QDir::homePath() + "/.app/icons" << ":/icons");
QFile icon("icons:open.png");   // the user's icon, or the built-in one

The prefix must be at least two characters long, so that it cannot be confused with a drive letter, and may contain only letters and digits; otherwise a warning is printed and nothing changes.

This function was introduced in 4.3.

See also addSearchPath() and searchPaths().

void QDir::setSorting(SortFlags sort)

Sets the sort order used by entryList() and entryInfoList() to sort.

See also sorting().

SortFlags QDir::sorting() const

Returns the sort order used by entryList() and entryInfoList().

See also setSorting().

void QDir::swap(QDir &other)

Exchanges this directory with other.

[static] QDir QDir::temp()

Returns a QDir for the system's temporary directory.

See also tempPath().

[static] QString QDir::tempPath()

Returns the path of the system's temporary directory. It is taken from TMPDIR and falls back to /tmp.

See also temp().

[static] QString QDir::toNativeSeparators(const QString &path)

Returns path unchanged; native paths already use / on Nt.

See also fromNativeSeparators().