Qt Toolkit - QDir Class

# QDir Class Reference

Traverses directory structures and contents in a platform-independent way. More...

`#include <qdir.h>`

List of all member functions.

## Public Members

- QDir ()
- QDir ( const char * path, const char * nameFilter = 0, int sortSpec = Name | IgnoreCase, int filterSpec = All )
- QDir ( const QDir & )
- ~QDir ()
- QDir& operator= ( const QDir & )
- QDir& operator= ( const char * path )
- void setPath ( const char * path )
- const char* path () const
- QString absPath () const
- QString canonicalPath () const
- QString dirName () const
- QString filePath ( const char * fileName, bool acceptAbsPath = TRUE ) const
- QString absFilePath ( const char * fileName, bool acceptAbsPath = TRUE ) const
- bool cd ( const char * dirName, bool acceptAbsPath = TRUE )
- bool cdUp ()
- const char* nameFilter () const
- void setNameFilter ( const char * nameFilter )
- FilterSpec filter () const
- void setFilter ( int filterSpec )
- SortSpec sorting () const
- void setSorting ( int sortSpec )
- bool matchAllDirs () const
- void setMatchAllDirs ( bool )
- uint count () const
- const char* operator[] ( int ) const
- const QStrList* entryList ( int filterSpec = DefaultFilter, int sortSpec = DefaultSort ) const
- const QStrList* entryList ( const char * nameFilter, int filterSpec = DefaultFilter, int sortSpec = DefaultSort ) const
- const QFileInfoList* entryInfoList ( int filterSpec = DefaultFilter, int sortSpec = DefaultSort ) const
- const QFileInfoList* entryInfoList ( const char * nameFilter, int filterSpec = DefaultFilter, int sortSpec = DefaultSort ) const
- bool mkdir ( const char * dirName, bool acceptAbsPath = TRUE ) const
- bool rmdir ( const char * dirName, bool acceptAbsPath = TRUE ) const
- bool isReadable () const
- bool exists () const
- bool isRoot () const
- bool isRelative () const
- void convertToAbs ()
- bool operator== ( const QDir & ) const
- bool operator!= ( const QDir & ) const
- bool remove ( const char * fileName, bool acceptAbsPath = TRUE )
- bool rename ( const char * name, const char * newName, bool acceptAbsPaths = TRUE )
- bool exists ( const char * name, bool acceptAbsPath = TRUE )

## Static Public Members

- QString convertSeparators ( const char * pathName )
- const QFileInfoList* drives ()
- char separator ()
- bool setCurrent ( const char * path )
- QDir current ()
- QDir home ()
- QDir root ()
- QString currentDirPath ()
- QString homeDirPath ()
- QString rootDirPath ()
- bool match ( const char * filter, const char * fileName )
- QString cleanDirPath ( const char * dirPath )
- bool isRelativePath ( const char * path )

## Detailed 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 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.

The directory "example" under the current directory is checked for existence in the example below:

        QDir d( "example" );                        // "./example"
        if ( !d.exists() )
            warning( "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"
            warning( "Cannot find the \"/tmp\" directory" );
        } else {
            QFile f( d.filePath("ex1.txt") );       // "/tmp/ex1.txt"
            if ( !f.open(IO_ReadWrite) )
                warning( "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
            QFileInfo *fi;                          // pointer for traversing

            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
            }
        }

Examples: dirview/dirview.cpp

## Member Function Documentation

### QDir::QDir ()

Constructs a QDir pointing to the current directory.

See also: currentDirPath().

### QDir::QDir ( const QDir & d )

Constructs a QDir that is a copy of the given directory.

See also: operator=().

### QDir::QDir ( const char * path, const char * nameFilter = 0, 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).

No check is made to ensure that the directory exists.

See also: exists(), setPath(), setNameFilter(), setFilter() and setSorting().

### QDir::~QDir ()

Destroys the QDir and cleans up.

### QString QDir::absFilePath ( const char * fileName, bool acceptAbsPath = TRUE ) const

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

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

Returns the canonical path, i.e. a path without symbolic links.

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 a null string is returned.

See also: path(), absPath(), exists(), cleanDirPath(), dirName(), absFilePath() and QString::isNull().

### bool QDir::cd ( const char * dirName, bool acceptAbsPath = TRUE )

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 new directory does not exist.

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() )
                  warning( "Cannot cd into \"%s\".", (char*)d.absFilePath("c++") );
              else
                  warning( "Cannot create directory \"%s\"\n"
                           "A file named \"c++\" already exists in \"%s\"",
                           (const char *)d.absFilePath("c++"),
                           (const char *)d.path() );
              return;
          } else {
              warning( "Creating directory \"%s\"",
                       (const char *) d.absFilePath("c++") );
              if ( !d.mkdir( "c++" ) ) {
                  warning("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 ()

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 char * 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.

### QString QDir::convertSeparators ( const char * 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 ()

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

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 if 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. "/").

### const QFileInfoList * QDir::entryInfoList ( const char * nameFilter, int filterSpec = DefaultFilter, int sortSpec = DefaultSort ) const

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.

See also: entryList(), setNameFilter(), setSorting() and setFilter().

### const QFileInfoList * QDir::entryInfoList ( int filterSpec = DefaultFilter, int sortSpec = DefaultSort ) const

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.

Returns 0 if the directory is unreadable or does not exist.

See also: entryList(), setNameFilter(), setSorting() and setFilter().

Examples: dirview/dirview.cpp

### const QStrList * QDir::entryList ( const char * nameFilter, int filterSpec = DefaultFilter, int sortSpec = DefaultSort ) const

Returns a list of the names of 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.

See also: entryInfoList(), setNameFilter(), setSorting() and setFilter().

### const QStrList * QDir::entryList ( int filterSpec = DefaultFilter, int sortSpec = DefaultSort ) const

Returns a list of the names of 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.

Returns 0 if the directory is unreadable or does not exist.

See also: entryInfoList(), setNameFilter(), setSorting() and setFilter().

### bool QDir::exists () const

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 char * name, bool acceptAbsPath = TRUE )

Checks for existence of a file.

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 char * fileName, bool acceptAbsPath = TRUE ) const

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()

See also: 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

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().

Examples: dirview/dirview.cpp

### bool QDir::isRelative () const

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 char * path ) `[static]`

Returns TRUE if the path is relative, FALSE if it is absolute.

See also: isRelative().

### bool QDir::isRoot () const

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() )
            warning( "It IS a root link!" );

See also: root() and rootDirPath().

### bool QDir::match ( const char * filter, const char * fileName ) `[static]`

Returns TRUE if the fileName matches the wildcard filter.

See also: QRegExp.

### bool QDir::matchAllDirs () const

Returns the value set by setMatchAllDirs()

See also: setMatchAllDirs().

### bool QDir::mkdir ( const char * dirName, bool acceptAbsPath = TRUE ) const

Creates a directory.

If acceptAbsPath is TRUE a path starting with a separator ('/') 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().

### const char * QDir::nameFilter () const

Returns the string set by setNameFilter()

See also: setNameFilter().

### bool QDir::operator!= ( const QDir & d ) const

Returns TRUE if the d and this dir havee different path or different sort/filter settings, otherwise FALSE.

### QDir & QDir::operator= ( const QDir & d )

Makes a copy of d and assigns it to this QDir.

### QDir & QDir::operator= ( const char * path )

Sets the directory path to be the given path.

### bool QDir::operator== ( const QDir & d ) const

Returns TRUE if the d and this dir have the same path and all sort and filter settings are equal, otherwise FALSE.

### const char * 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().

### const char * QDir::path () const

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 char * fileName, bool acceptAbsPath = TRUE )

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.

Returns TRUE if successful, otherwise FALSE.

### bool QDir::rename ( const char * name, const char * newName, bool acceptAbsPaths = TRUE )

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 char * dirName, bool acceptAbsPath = TRUE ) const

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.

### bool QDir::setCurrent ( const char * path ) `[static]`

Sets the the current directory. Returns TRUE if successful.

### void QDir::setFilter ( int filterSpec )

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(). The filter is specified by or-ing values from the enum FilterSpec. The different values are:

Dirs
  List directories only.
Files
  List files only.
Drives
  List drives.
NoSymLinks
  Do not list symbolic links.

Readable
  List files with read permission.
Writable
  List files with write permission.
Executable
  List files with execute permission.

  Setting none of the three flags above is equivalent to setting all of them.

Modified
  Only list files that have been modified (does nothing under UNIX).
Hidden
  List hidden files also (.* under UNIX).
System
  List system files (does nothing under UNIX).

See also: nameFilter().

### void QDir::setMatchAllDirs ( bool enable )

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 char * nameFilter )

Sets the name filter used by entryList() and entryInfoList().

The name filter is a wildcarding filter that understands "*" and "?" wildcards, if you want entryList() and entryInfoList() to list all files ending with ".cpp", you simply call dir.setNameFilter("*.cpp");

See also: nameFilter().

### void QDir::setPath ( const char * path )

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.

See also: path(), absPath(), exists, cleanDirPath(), dirName(), absFilePath(), isRelative() and convertToAbs().

### void QDir::setSorting ( int sortSpec )

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().

Search the documentation, FAQ, qt-interest archive and more (uses www.troll.no):

This file is part of the Qt toolkit, copyright © 1995-99 Troll Tech, all rights reserved.

It was generated from the following files:

- qdir.h: 1998/08/19
- qdir.cpp: 1999/02/22