QDir - Traverses directory structures and contents in a
platform-independent way
#include <qdir.h>
Public Members
enum FilterSpec { Dirs = 0x001, Files = 0x002, Drives =
0x004, NoSymLinks = 0x008, All = 0x007, TypeMask =
0x00F, Readable = 0x010, Writable = 0x020, Executable
= 0x040, RWEMask = 0x070, Modified = 0x080, Hidden =
0x100, System = 0x200, AccessMask = 0x3F0,
DefaultFilter = -1 }
enum SortSpec { Name = 0x00, Time = 0x01, Size = 0x02,
Unsorted = 0x03, SortByMask = 0x03, DirsFirst = 0x04,
Reversed = 0x08, IgnoreCase = 0x10, DefaultSort = -1 }
QDir ()
QDir ( const QString & path, const QString & nameFilter =
QString::null, int sortSpec = Name | IgnoreCase, int
filterSpec = All )
QDir ( const QDir & )
virtual ~QDir ()
QDir& operator= ( const QDir & )
QDir& operator= ( const QString & path )
virtual void setPath ( const QString & path )
virtual QString path () const
virtual QString absPath () const
virtual QString canonicalPath () const
virtual QString dirName () const
virtual QString filePath ( const QString & fileName, bool
acceptAbsPath = TRUE ) const
virtual QString absFilePath ( const QString & fileName,
bool acceptAbsPath = TRUE ) const
virtual bool cd ( const QString & dirName, bool
acceptAbsPath = TRUE )
virtual bool cdUp ()
QString nameFilter () const
virtual void setNameFilter ( const QString & nameFilter )
FilterSpec filter () const
virtual void setFilter ( int filterSpec )
SortSpec sorting () const
virtual void setSorting ( int sortSpec )
bool matchAllDirs () const
virtual void setMatchAllDirs ( bool )
uint count () const
QString operator[] ( int ) const
virtual QStrList encodedEntryList ( int filterSpec =
DefaultFilter, int sortSpec = DefaultSort ) const
virtual QStrList encodedEntryList ( const QString &
nameFilter, int filterSpec = DefaultFilter, int
sortSpec = DefaultSort ) const
virtual QStringList entryList ( int filterSpec =
DefaultFilter, int sortSpec = DefaultSort ) const
nameFilter, int filterSpec = DefaultFilter, int
sortSpec = DefaultSort ) const
virtual const QFileInfoList* entryInfoList ( int
filterSpec = DefaultFilter, int sortSpec = DefaultSort
) const
virtual const QFileInfoList* entryInfoList ( const QString
& nameFilter, int filterSpec = DefaultFilter, int
sortSpec = DefaultSort ) const
virtual bool mkdir ( const QString & dirName, bool
acceptAbsPath = TRUE ) const
virtual bool rmdir ( const QString & dirName, bool
acceptAbsPath = TRUE ) const
virtual bool isReadable () const
virtual bool exists () const
virtual bool isRoot () const
virtual bool isRelative () const
virtual void convertToAbs ()
virtual bool operator== ( const QDir & ) const
virtual bool operator!= ( const QDir & ) const
virtual bool remove ( const QString & fileName, bool
acceptAbsPath = TRUE )
virtual bool rename ( const QString & name, const QString
& newName, bool acceptAbsPaths = TRUE )
virtual bool exists ( const QString & name, bool
acceptAbsPath = TRUE )
Static Public Members
QString convertSeparators ( const QString & pathName )
const QFileInfoList* drives ()
char separator ()
bool setCurrent ( const QString & path )
QDir current ()
QDir home ()
QDir root ()
QString currentDirPath ()
QString homeDirPath ()
QString rootDirPath ()
bool match ( const QStringList & filters, const QString &
fileName )
bool match ( const QString & filter, const QString &
fileName )
QString cleanDirPath ( const QString & dirPath )
bool isRelativePath ( const QString & path )
DESCRIPTION
Traverses directory structures and contents in a platform-
independent way.
A QDir can point to a file using either a relative or an
absolute file path. Absolute file paths begin with the
directory separator ('/') or a drive specification (not
applicable to UNIX). Relative file names begin with a
directory name or a file name and specify a path relative
An example of an absolute path is the string
"/tmp/quartz", a relative path might look like
"src/fatlib". You can use the function isRelative() to
check if a QDir is using a relative or an absolute file
path. You can call the function convertToAbs() to convert
a relative QDir to an absolute one.
The directory "example" under the current directory is
checked for existence in the example below:
QDir d( "example" ); // "./example"
if ( !d.exists() )
qWarning( "Cannot find the example directory" );
If you always use '/' as a directory separator, Qt will
translate your paths to conform to the underlying
operating system.
cd() and cdUp() can be used to navigate the directory
tree. Note that the logical cd and cdUp operations are not
performed if the new directory does not exist.
Example:
QDir d = QDir::root(); // "/"
if ( !d.cd("tmp") ) { // "/tmp"
qWarning( "Cannot find the \"/tmp\" directory" );
} else {
QFile f( d.filePath("ex1.txt") ); // "/tmp/ex1.txt"
if ( !f.open(IO_ReadWrite) )
qWarning( "Cannot create the file %s", f.name() );
}
To read the contents of a directory you can use the
entryList() and entryInfoList() functions.
Example:
#include <stdio.h>
#include <qdir.h>
//
// This program scans the current directory and lists all files
// that are not symbolic links, sorted by size with the smallest files
// first.
//
int main( int argc, char **argv )
{
QDir d;
d.setFilter( QDir::Files | QDir::Hidden | QDir::NoSymLinks );
d.setSorting( QDir::Size | QDir::Reversed );
const QFileInfoList *list = d.entryInfoList();
QFileInfoListIterator it( *list ); // create list iterator
printf( " BYTES FILENAME\n" ); // print header
while ( (fi=it.current()) ) { // for each file...
printf( "%10li %s\n", fi->size(), fi->fileName().data() );
++it; // goto next list element
}
}
Member Type Documentation
QDir::FilterSpec
This enum describes how QDir is to select what entries in
a directory to return. The filter value is specified by
or-ing together values from the following list:
Dirs - List directories only
Files - List files only
Drives - List disk drives (does nothing under unix)
NoSymLinks - Do not list symbolic links (where they exist)
Readable - List files for which the application has read
access.
Writable - List files for which the application has write
access.
Executable - List files for which the application has
execute access
Modified - Only list files that have been modified (does
nothing under unix)
Hidden - List hidden files (on unix, files starting with a
.)
System - List system files (does nothing under unix)
If you do not set any of Readable, Writable or Executable,
QDir will set all three of them. This makes the default
easy to write and at the same time useful.
Examples: application has read access, write access or
both. Dirs|Drives means list drives, directories, all
files that the application can read, write or execute, and
also symlinks to such files/directories.
QDir::SortSpec
This enum describes how QDir is to sort entries in a
directory when it returns a list of them. The sort value
is specified by or-ing together values from the following
list:
Time - sort by time (modification time)
Size - sort by file size
Unsorted - do not sort
DirsFirst - put all directories first in the list
Reversed - reverse the sort order
IgnoreCase - sort case-insensitively
You can only specify one of the first four. If you specify
both DirsFirst and Reversed, directories are still put
first but the list is otherwise reversed.
MEMBER FUNCTION DOCUMENTATION
QDir::QDir ()
Constructs a QDir pointing to the current directory.
See also currentDirPath().
QDir::QDir ( const QString & path, const QString & nameFilter =
QString::null, int sortSpec = Name | IgnoreCase, int
filterSpec = All )
Constructs a QDir.
Arguments:
path is the directory.
nameFilter is the file name filter.
sortSpec is the sort specification, which describes how to
sort the files in the directory.
filterSpec is the filter specification, which describes
how to filter the files in the directory. Most of
these arguments (except path) have optional values.
Example:
// lists all files in /tmp
QDir d( "/tmp" );
for ( int i=0; i<d.count(); i++ )
printf( "%s\n", d[i] );
If path is "" or null, the directory is set to "." (the
current directory). If nameFilter is "" or null, it is set
to "*" (all files).
See also exists(), setPath(), setNameFilter(), setFilter()
and setSorting().
QDir::QDir ( const QDir & d )
Constructs a QDir that is a copy of the given directory.
See also operator=().
QDir::~QDir () [virtual]
Destructs the QDir and cleans up.
QString QDir::absFilePath ( const QString & fileName, bool
acceptAbsPath = TRUE ) const [virtual]
Returns the absolute path name of a file in the directory.
Does NOT check if the file actually exists in the
directory. Redundant multiple separators or "." and ".."
directories in fileName will NOT be removed (see
cleanDirPath()).
If acceptAbsPath is TRUE a fileName starting with a
separator ('/') will be returned without change. if
acceptAbsPath is FALSE an absolute path will be appended
to the directory path.
See also filePath().
QString QDir::absPath () const [virtual]
Returns the absolute (a path that starts with '/') path,
which may contain symbolic links, but never contains
redundant ".", ".." or multiple separators.
See also setPath(), canonicalPath(), exists(),
cleanDirPath(), dirName() and absFilePath().
QString QDir::canonicalPath () const [virtual]
Returns the canonical path, i.e. a path without symbolic
links or redundant "." or ".." elements.
On systems that do not have symbolic links this function
will always return the same string that absPath returns.
If the canonical path does not exist (normally due to
dangling symbolic links) canonicalPath() returns a null
string.
See also path(), absPath(), exists(), cleanDirPath(),
dirName(), absFilePath() and QString::isNull().
bool QDir::cd ( const QString & dirName, bool acceptAbsPath =
TRUE ) [virtual]
Changes directory by descending into the given directory.
Returns TRUE if the new directory exists and is readable.
Note that the logical cd operation is NOT performed if the
If acceptAbsPath is TRUE a path starting with a separator
('/') will cd to the absolute directory, if acceptAbsPath
is FALSE any number of separators at the beginning of
dirName will be removed.
Example:
QDir d = QDir::home(); // now points to home directory
if ( !d.cd("c++") ) { // now points to "c++" under home directory if OK
QFileInfo fi( d, "c++" );
if ( fi.exists() ) {
if ( fi.isDir() )
qWarning( "Cannot cd into \"%s\".", (char*)d.absFilePath("c++") );
else
qWarning( "Cannot create directory \"%s\"\n"
"A file named \"c++\" already exists in \"%s\"",
(const char *)d.absFilePath("c++"),
(const char *)d.path() );
return;
} else {
qWarning( "Creating directory \"%s\"",
(const char *) d.absFilePath("c++") );
if ( !d.mkdir( "c++" ) ) {
qWarning("Could not create directory \"%s\"",
(const char *)d.absFilePath("c++") );
return;
}
}
}
Calling cd( ".." ) is equivalent to calling cdUp().
See also cdUp(), isReadable(), exists() and path().
bool QDir::cdUp () [virtual]
Changes directory by moving one directory up the path
followed to arrive at the current directory.
Returns TRUE if the new directory exists and is readable.
Note that the logical cdUp() operation is not performed if
the new directory does not exist.
See also cd(), isReadable(), exists() and path().
QString QDir::cleanDirPath ( const QString & filePath ) [static]
Removes all multiple directory separators ('/') and
resolves any "." or ".." found in the path.
Symbolic links are kept. This function does not return the
canonical path, but rather the most simplified version of
the input." and "\\stuff\\more\\..\\nonsense" becomes
"\\stuff\\nonsense".
QString QDir::convertSeparators ( const QString & pathName )
[static]
Converts the '/' separators in pathName to system native
separators. Returns the translated string.
On Windows, convertSeparators("c:/winnt/system32")
returns" c:\winnt\system32".
No conversion is done on UNIX.
void QDir::convertToAbs () [virtual]
Converts the directory path to an absolute path. If it is
already absolute nothing is done.
See also isRelative().
uint QDir::count () const
Returns the number of files that was found. Equivalent to
entryList().count().
See also operator[]() and entryList().
QDir QDir::current () [static]
Returns the current directory.
See also currentDirPath() and QDir::QDir().
QString QDir::currentDirPath () [static]
Returns the absolute path of the current directory.
See also current().
QString QDir::dirName () const [virtual]
Returns the name of the directory, this is NOT the same as
the path, e.g. a directory with the name "mail", might
have the path "/var/spool/mail". If the directory has no
name (e.g. the root directory) a null string is returned.
No check is made to ensure that a directory with this name
actually exists.
See also path(), absPath(), absFilePath(), exists() and
QString::isNull().
const QFileInfoList * QDir::drives () [static]
Returns a list of the root directories on this system. On
win32, this returns a number of QFileInfo objects
containing "C:/"," D:/" etc. On other operating systems,
it returns a list containing just one root directory (e.g.
"/").
The returned pointer is owned by Qt. Callers should not
QStrList QDir::encodedEntryList ( const QString & nameFilter, int
filterSpec = DefaultFilter, int sortSpec = DefaultSort )
const [virtual]
This function is included to easy porting from Qt 1.x to
Qt 2.0, it is the same as entryList(), but encodes the
filenames as 8-bit strings using QFile::encodedName().
It is more efficient to use entryList().
QStrList QDir::encodedEntryList ( int filterSpec = DefaultFilter,
int sortSpec = DefaultSort ) const [virtual]
This function is included to easy porting from Qt 1.x to
Qt 2.0, it is the same as entryList(), but encodes the
filenames as 8-bit strings using QFile::encodedName().
It is more efficient to use entryList().
const QFileInfoList * QDir::entryInfoList ( const QString &
nameFilter, int filterSpec = DefaultFilter, int sortSpec =
DefaultSort ) const [virtual]
Returns a list of QFileInfo objects for all files and
directories in the directory pointed to using the
setSorting(), setFilter() and setNameFilter()
specifications.
The the filter and sorting specifications can be
overridden using the nameFilter, filterSpec and sortSpec
arguments.
Returns 0 if the directory is unreadable or does not
exist.
The returned pointer is a const pointer to a
QFileInfoList. The list is owned by the QDir object and
will be reused on the next call to entryInfoList() for the
same QDir instance. If you want to keep the entries of the
list after a subsequent call to this function you will
need to copy them.
See also entryList(), setNameFilter(), setSorting() and
setFilter().
const QFileInfoList * QDir::entryInfoList ( int filterSpec =
DefaultFilter, int sortSpec = DefaultSort ) const
[virtual]
Returns a list of QFileInfo objects for all files and
directories in the directory pointed to using the
setSorting(), setFilter() and setNameFilter()
specifications.
The the filter and sorting specifications can be
overridden using the filterSpec and sortSpec arguments.
exist.
The returned pointer is a const pointer to a
QFileInfoList. The list is owned by the QDir object and
will be reused on the next call to entryInfoList() for the
same QDir instance. If you want to keep the entries of the
list after a subsequent call to this function you will
need to copy them.
See also entryList(), setNameFilter(), setSorting() and
setFilter().
QStringList QDir::entryList ( const QString & nameFilter, int
filterSpec = DefaultFilter, int sortSpec = DefaultSort )
const [virtual]
Returns a list of the names of all files and directories
in the directory indicated by the setSorting(),
setFilter() and setNameFilter() specifications.
The the filter and sorting specifications can be
overridden using the nameFilter, filterSpec and sortSpec
arguments.
Returns and empty list if the directory is unreadable or
does not exist.
See also entryInfoList(), setNameFilter(), setSorting(),
setFilter() and encodedEntryList().
QStringList QDir::entryList ( int filterSpec = DefaultFilter, int
sortSpec = DefaultSort ) const [virtual]
Returns a list of the names of all files and directories
in the directory indicated by the setSorting(),
setFilter() and setNameFilter() specifications.
The the filter and sorting specifications can be
overridden using the filterSpec and sortSpec arguments.
Returns an empty list if the directory is unreadable or
does not exist.
See also entryInfoList(), setNameFilter(), setSorting(),
setFilter() and encodedEntryList().
bool QDir::exists () const [virtual]
Returns TRUE if the directory exists. (If a file with the
same name is found this function will of course return
FALSE).
See also QFileInfo::exists() and QFile::exists().
bool QDir::exists ( const QString & name, bool acceptAbsPath =
TRUE ) [virtual]
If acceptAbsPaths is TRUE a path starting with a separator
('/') will check the file with the absolute path, if
acceptAbsPath is FALSE any number of separators at the
beginning of name will be removed.
Returns TRUE if the file exists, otherwise FALSE.
See also QFileInfo::exists() and QFile::exists().
QString QDir::filePath ( const QString & fileName, bool
acceptAbsPath = TRUE ) const [virtual]
Returns the path name of a file in the directory. Does NOT
check if the file actually exists in the directory. If the
QDir is relative the returned path name will also be
relative. Redundant multiple separators or "." and ".."
directories in fileName will not be removed (see
cleanDirPath()).
If acceptAbsPath is TRUE a fileName starting with a
separator ('/') will be returned without change. If
acceptAbsPath is FALSE an absolute path will be appended
to the directory path.
See also absFilePath(), isRelative() and canonicalPath().
QDir::FilterSpec QDir::filter() const
Returns the value set by setFilter().
QDir QDir::home () [static]
Returns the home directory.
See also homeDirPath().
QString QDir::homeDirPath () [static]
Returns the absolute path for the user's home directory,
See also home().
bool QDir::isReadable () const [virtual]
Returns TRUE if the directory is readable AND we can open
files by name. This function will return FALSE if only one
of these is present.
Warning: A FALSE value from this function is not a
guarantee that files in the directory are not accessible.
See also QFileInfo::isReadable().
bool QDir::isRelative () const [virtual]
Returns TRUE if the directory path is relative to the
current directory, FALSE if the path is absolute (e.g.
under UNIX a path is relative if it does not start with a
According to Einstein this function should always return
TRUE.
See also convertToAbs().
bool QDir::isRelativePath ( const QString & path ) [static]
Returns TRUE if the path is relative, FALSE if it is
absolute.
See also isRelative().
bool QDir::isRoot () const [virtual]
Returns TRUE if the directory is the root directory,
otherwise FALSE.
Note: If the directory is a symbolic link to the root
directory this function returns FALSE. If you want to test
for this you can use canonicalPath():
Example:
QDir d( "/tmp/root_link" );
d = d.canonicalPath();
if ( d.isRoot() )
qWarning( "It IS a root link!" );
See also root() and rootDirPath().
bool QDir::match ( const QString & filter, const QString &
fileName ) [static]
Returns TRUE if the fileName matches the wildcard filter.
Filter may also contain multiple wildcards separated by
spaces or semicolons.
See also QRegExp.
bool QDir::match ( const QStringList & filters, const QString &
fileName ) [static]
Returns TRUE if the fileName matches one of the wildcards
in the list filters.
See also QRegExp.
bool QDir::matchAllDirs () const
Returns the value set by setMatchAllDirs()
See also setMatchAllDirs().
bool QDir::mkdir ( const QString & dirName, bool acceptAbsPath =
TRUE ) const [virtual]
Creates a directory.
('/') will create the absolute directory, if acceptAbsPath
is FALSE any number of separators at the beginning of
dirName will be removed.
Returns TRUE if successful, otherwise FALSE.
See also rmdir().
QString QDir::nameFilter () const
Returns the string set by setNameFilter().
bool QDir::operator!= ( const QDir & d ) const [virtual]
Returns TRUE if the d and this dir have different path or
different sort/filter settings, otherwise FALSE.
QDir & QDir::operator= ( const QString & path )
Sets the directory path to be the given path.
QDir & QDir::operator= ( const QDir & d )
Makes a copy of d and assigns it to this QDir.
bool QDir::operator== ( const QDir & d ) const [virtual]
Returns TRUE if the d and this dir have the same path and
all sort and filter settings are equal, otherwise FALSE.
QString QDir::operator[] ( int index ) const
Returns the file name at position index in the list of
found file names. Equivalent to entryList().at(index).
Returns null if the index is out of range or if the
entryList() function failed.
See also count() and entryList().
QString QDir::path () const [virtual]
Returns the path, this may contain symbolic links, but
never contains redundant ".", ".." or multiple separators.
The returned path can be either absolute or relative (see
setPath()).
See also setPath(), absPath(), exists(), cleanDirPath(),
dirName(), absFilePath() and convertSeparators().
bool QDir::remove ( const QString & fileName, bool acceptAbsPath
= TRUE ) [virtual]
Removes a file.
If acceptAbsPath is TRUE a path starting with a separator
('/') will remove the file with the absolute path, if
acceptAbsPath is FALSE any number of separators at the
beginning of fileName will be removed.
bool QDir::rename ( const QString & name, const QString &
newName, bool acceptAbsPaths = TRUE ) [virtual]
Renames a file.
If acceptAbsPaths is TRUE a path starting with a separator
('/') will rename the file with the absolute path, if
acceptAbsPath is FALSE any number of separators at the
beginning of name will be removed.
Returns TRUE if successful, otherwise FALSE.
On most file systems, rename() fails only if oldName does
not exist or if newName and oldName are not on the same
partition, but there are also other reasons why rename()
can fail. For example, on at least one file system
rename() fails if newName points to an open file.
bool QDir::rmdir ( const QString & dirName, bool acceptAbsPath =
TRUE ) const [virtual]
Removes a directory.
If acceptAbsPath is TRUE a path starting with a separator
('/') will remove the absolute directory, if acceptAbsPath
is FALSE any number of separators at the beginning of
dirName will be removed.
The directory must be empty for rmdir() to succeed.
Returns TRUE if successful, otherwise FALSE.
See also mkdir().
QDir QDir::root () [static]
Returns the root directory.
See also rootDirPath() and drives().
QString QDir::rootDirPath () [static]
Returns the absolute path for the root directory ("/"
under UNIX).
See also root() and drives().
char QDir::separator () [static]
Returns the native directory separator; '/' under UNIX and
'\' under MS-DOS, Windows NT and OS/2.
You do not need to use this function to build file paths.
If you always use '/', Qt will translate your paths to
conform to the underlying operating system.
Sets the the current directory. Returns TRUE if
successful.
void QDir::setFilter ( int filterSpec ) [virtual]
Sets the filter used by entryList() and entryInfoList().
The filter is used to specify the kind of files that
should be returned by entryList() and entryInfoList().
See also filter() and setNameFilter().
void QDir::setMatchAllDirs ( bool enable ) [virtual]
If enable is TRUE, all directories will be listed (even if
they do not match the filter or the name filter),
otherwise only matched directories will be listed.
See also matchAllDirs().
Bugs and limitations:
Currently, directories that do not match the filter will
not be included (the name filter will be ignored as
expected).
void QDir::setNameFilter ( const QString & nameFilter ) [virtual]
Sets the name filter used by entryList() and
entryInfoList().
The name filter is a wildcarding filter that understands
"*" and "?" wildcards, You may specify several filter
entries separated by a " " or a ";". If you want
entryList() and entryInfoList() to list all files ending
with" dir.setNameFilter("*.cpp *.h") or
dir.setNameFilter("*.cpp;*.h")
See also nameFilter() and setFilter().
void QDir::setPath ( const QString & path ) [virtual]
Sets the path of the directory. The path is cleaned of
redundant ".", ".." and multiple separators. No check is
made to ensure that a directory with this path exists.
The path can be either absolute or relative. Absolute
paths begin with the directory separator ('/') or a drive
specification (not applicable to UNIX). Relative file
names begin with a directory name or a file name and
specify a path relative to the current directory. An
example of an absolute path is the string "/tmp/quartz", a
relative path might look like" src/fatlib". You can use
the function isRelative() to check if a QDir is using a
relative or an absolute file path. You can call the
function convertToAbs() to convert a relative QDir to an
absolute one.
dirName(), absFilePath(), isRelative() and convertToAbs().
void QDir::setSorting ( int sortSpec ) [virtual]
Sets the sorting order used by entryList() and
entryInfoList().
The sortSpec is specified by or-ing values from the enum
SortSpec. The different values are:
One of these:
Name
Sort by name (alphabetical order).
Time
Sort by time (most recent first).
Size
Sort by size (largest first).
Unsorted
Use the operating system order (UNIX does NOT sort
alphabetically).
ORed with zero or more of these:
DirsFirst
Always put directory names first.
Reversed
Reverse sort order.
IgnoreCase
Ignore case when sorting by name.
QDir::SortSpec QDir::sorting() const
Returns the value set by setSorting()
See also setSorting().
SEE ALSO
http://doc.trolltech.com/qdir.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
AUTHOR
Generated automatically from the source code.
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page (qdir.3qt) and
the Qt version (2.3.1).
Man(1) output converted with
man2html