Qore Programming Language Reference Manual  1.7.0
Qore::Dir Class Reference

This class implements directory handling, file listing, creating/removing subdirectories, etc. More...

Public Member Methods

bool chdir (string path)
 Changes the current directory of the Dir object to the path given. More...
 
nothing chgrp (int gid)
 Change the group membership of the directory from the group id. More...
 
nothing chgrp (string groupname)
 Change the group membership of the directory. More...
 
nothing chmod (softint mode)
 Changes the mode of the directory. More...
 
nothing chown (int uid)
 Change the ownership of the directory from the userid. More...
 
nothing chown (string username)
 Change the ownership of the directory from the username. More...
 
 constructor (*string encoding)
 Creates the Directory object. More...
 
 copy ()
 Creates a new directory object with the same character encoding specification and the same path as the original. More...
 
int create (softint mode=0777)
 Creates the directory tree the Dir object points to, if it does not exist. More...
 
bool exists ()
 Returns True if the path in the Dir object points to a directory that already exists and is openable by the current user, False otherwise. More...
 
hash< StatInfohstat ()
 Returns a StatInfo hash of file status information for the current directory. More...
 
list< auto > list (bool full=False)
 Get all entries in this directory, except "." and ".." directories; if any errors occur an exception is thrown. More...
 
list< auto > list (string regex, softint regex_options=0, softbool full=False)
 Gets all entries in the directory that match the given regular expression (except "." and ".." directories); if any errors occur an exception is thrown. More...
 
list< auto > listDirs (bool full=False)
 Retrieves all subdirectory entries in this directory, except "." and ".." directories; if any errors occur an exception is thrown. More...
 
list< auto > listDirs (string regex, softint regex_options=0, softbool full=False)
 Gets all subdirectory entries in the directory that match the given regular expression (except "." and ".." directories); if any errors occur an exception is thrown. More...
 
list< auto > listFiles (bool full=False)
 Retrieves all files in this directory; if any errors occur an exception is thrown. More...
 
list< auto > listFiles (string regex, softint regex_options=0, softbool full=False)
 Retrieves all files in the directory that match the given regular expression; if any errors occur an exception is thrown. More...
 
nothing mkdir (string subdir, softint mode=0777)
 Creates a direct subdirectory in the Dir object's current path. More...
 
Dir openDir (string subdir, *string encoding)
 Get a Dir object as an subdir entry of the current directory. More...
 
File openFile (string filename, int flags=O_RDONLY, int mode=0666, *string encoding)
 Create and open a File object in the current directory of the Dir object. More...
 
*string path ()
 Returns the path of the Dir object or NOTHING if no path is set. More...
 
bool removeFile (string file)
 Remove the file with the given name in the Dir object's directory. More...
 
nothing rmdir (string subdir)
 Removes a direct subdirectory from the Dir object's current path. More...
 
list< auto > stat ()
 Returns a list of file status information for the current directory. More...
 
hash< FilesystemInfostatvfs ()
 Returns a FilesystemInfo hash for the current directory. More...
 

Detailed Description

This class implements directory handling, file listing, creating/removing subdirectories, etc.

Restrictions:
Qore::PO_NO_FILESYSTEM

The Dir class allows Qore programs to list and manipulate directories.

Directory objects can be created/opened with a specific character encoding. This means that any entry read from the directory will be tagged with the directory's character encoding. If no character encoding is given the default character encoding is assumed.

Note
This class is not available with the PO_NO_FILESYSTEM parse option

Member Function Documentation

◆ chdir()

bool Qore::Dir::chdir ( string  path)

Changes the current directory of the Dir object to the path given.

If this method returns False then the directory can be created by calling Dir::create()

Parameters
pathThe path can be either an absolute path (leading with '/') or a directory relative to the actual path
Returns
True if the new path is openable as directory (see Dir::exists())
Example:
if (!d.chdir("../doc")) {
d.create(0755);
}
Note
calls to change to the current directory "." have no effect
Exceptions
DIR-CHDIR-ERRORcannot change to relative directory because no current directory is set

◆ chgrp() [1/2]

nothing Qore::Dir::chgrp ( int  gid)

Change the group membership of the directory from the group id.

Parameters
gidthe groupid of the user to change the directory to
Platform Availability:
Qore::Option::HAVE_UNIX_FILEMGT
Example:
try {
dir.chgrp(gid);
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-CHOWN-ERRORcannot change directory owner; no directory is set
DIR-CHOWN-FAILUREerror changing directory owner (arg will be assigned to the errno value)

◆ chgrp() [2/2]

nothing Qore::Dir::chgrp ( string  groupname)

Change the group membership of the directory.

Parameters
groupnamethe group name of the group to change the directory to
Platform Availability:
Qore::Option::HAVE_UNIX_FILEMGT
Example:
try {
dir.chgrp(groupname);
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-CHGRP-PARAMETER-ERRORno userid found for user
DIR-CHOWN-ERRORcannot change directory owner; no directory is set
DIR-CHOWN-FAILUREerror changing directory owner (arg will be assigned to the errno value)

◆ chmod()

nothing Qore::Dir::chmod ( softint  mode)

Changes the mode of the directory.

Parameters
modeThe mode of the directory
Example:
try {
dir.chmod(0750);
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-CHMOD-ERRORcannot change directory's mode; no directory is set
DIR-CHMOD-FAILUREerror changing directory's mode (arg will be assigned to the errno value)

◆ chown() [1/2]

nothing Qore::Dir::chown ( int  uid)

Change the ownership of the directory from the userid.

Parameters
uidthe userid of the user to change the directory to
Platform Availability:
Qore::Option::HAVE_UNIX_FILEMGT
Example:
try {
dir.chown(uid);
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-CHOWN-ERRORcannot change directory owner; no directory is set
DIR-CHOWN-FAILUREerror changing directory owner (arg will be assigned to the errno value)

◆ chown() [2/2]

nothing Qore::Dir::chown ( string  username)

Change the ownership of the directory from the username.

Parameters
usernamethe username of the user to change the directory to
Platform Availability:
Qore::Option::HAVE_UNIX_FILEMGT
Example:
try {
dir.chown(username);
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-CHOWN-PARAMETER-ERRORno userid found for user
DIR-CHOWN-ERRORcannot change directory owner; no directory is set
DIR-CHOWN-FAILUREerror changing directory owner (arg will be assigned to the errno value)

◆ constructor()

Qore::Dir::constructor ( *string  encoding)

Creates the Directory object.

The object will point to the currect directory of the process

Parameters
encodingthe name of the default character encoding for filenames retrieved; if this argument is not given, filename strings retrieved will be tagged with the default character encoding of the process
Example:
Dir dir("utf-8");

◆ copy()

Qore::Dir::copy ( )

Creates a new directory object with the same character encoding specification and the same path as the original.

Example:
Dir nd = dir.copy();

◆ create()

int Qore::Dir::create ( softint  mode = 0777)

Creates the directory tree the Dir object points to, if it does not exist.

Parameters
modeThe mode of the directory
Returns
the number of directories actually created
Example:
if (!d.exists()) {
try {
printf("%y: does not exist; creating...\n", d.path());
cnt = d.create(0755);
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
}
string printf(string fmt,...)
Outputs the string passed to standard output, using the first argument as a format string; does not e...
Exceptions
DIR-CREATE-ERRORcannot create directory; no directory is set
DIR-CREATE-FAILUREerror creating directory (arg will be assigned to the errno value)

◆ exists()

bool Qore::Dir::exists ( )

Returns True if the path in the Dir object points to a directory that already exists and is openable by the current user, False otherwise.

Returns
True if the path in the Dir object points to a directory that already exists and is openable by the current user, False otherwise
Example:
if (!d.exists())
printf("%y: does not exist or cannot be opened\n", d.path());

◆ hstat()

hash<StatInfo> Qore::Dir::hstat ( )

Returns a StatInfo hash of file status information for the current directory.

If any errors occur an exception will be thrown

Returns
a StatInfo hash giving information about the current directory
Example:
try {
hash<StatInfo> h = dir.hstat();
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-HSTAT-ERRORno directory is set
DIR-HSTAT-FAILUREerror stat'ing directory (arg will be assigned to the errno value)

◆ list() [1/2]

list<auto> Qore::Dir::list ( bool  full = False)

Get all entries in this directory, except "." and ".." directories; if any errors occur an exception is thrown.

This method uses stat() system call internally to get detailed info about directory entries if the full parameter is True. If a stat() call fails for an entry, the entry is skipped and information about it is not included in the returned list.

Parameters
fullif True then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Returns
a list of all entries in the directory (except "." and ".." directories); if full is True, then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Example:
try {
map printf("entry: %s\n", $1), d.list();
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-READ-ERRORno directory is set
DIR-READ-FAILUREerror reading directory (arg will be assigned to the errno value)
Since
Qore 0.8.8 added the full parameter

◆ list() [2/2]

list<auto> Qore::Dir::list ( string  regex,
softint  regex_options = 0,
softbool  full = False 
)

Gets all entries in the directory that match the given regular expression (except "." and ".." directories); if any errors occur an exception is thrown.

This method uses stat() system call internally to get info about directory entries. If a stat() call fails for an entry, the entry is skipped and information about it is not included in the returned list.

Parameters
regexa regular expression string used to filter the arguments (note that this is not a glob, but rather a regular expression string)
regex_optionsoptional bitwise-or'ed regex option constants
fullif True then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Returns
a list of all entries in the directory that match the given regular expression (except "." and ".." directories); if full is True, then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Example:
try {
foreach string e in (d.list("\\.txt$")) {
printf("entry: %s\n");
}
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-READ-ERRORno directory is set
DIR-READ-FAILUREerror reading directory (arg will be assigned to the errno value)
REGEX-COMPILATION-ERRORerror in regular expression
REGEX-OPTION-ERRORregex option argument contains invalid option bits
Since
Qore 0.8.8 added the full parameter

◆ listDirs() [1/2]

list<auto> Qore::Dir::listDirs ( bool  full = False)

Retrieves all subdirectory entries in this directory, except "." and ".." directories; if any errors occur an exception is thrown.

This method uses stat() system call internally to get info about directory entries. If a stat() call fails for an entry, the entry is skipped and information about it is not included in the returned list.

Parameters
fullif True then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Returns
a list of all subdirectory entries in this directory, except "." and ".." directories; if full is True, then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Example:
try {
foreach string e in (d.listDirs()) {
printf("entry: %s\n");
}
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-READ-ERRORno directory is set
DIR-READ-FAILUREerror reading directory (arg will be assigned to the errno value)
Since
Qore 0.8.8 added the full parameter

◆ listDirs() [2/2]

list<auto> Qore::Dir::listDirs ( string  regex,
softint  regex_options = 0,
softbool  full = False 
)

Gets all subdirectory entries in the directory that match the given regular expression (except "." and ".." directories); if any errors occur an exception is thrown.

This method uses stat() system call internally to get info about directory entries. If a stat() call fails for an entry, the entry is skipped and information about it is not included in the returned list.

Parameters
regexa regular expression string used to filter the arguments (note that this is not a glob, but rather a regular expression string)
regex_optionsoptional bitwise-or'ed regex option constants
fullif True then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Returns
a list of all subdirectory entries in the directory that match the given regular expression (except "." and ".." directories); if full is True, then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Example:
try {
foreach string e in (d.listDirs("^pgsql-")) {
printf("entry: %s\n");
}
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-READ-ERRORno directory is set
DIR-READ-FAILUREerror reading directory (arg will be assigned to the errno value)
REGEX-COMPILATION-ERRORerror in regular expression
REGEX-OPTION-ERRORregex option argument contains invalid option bits
Since
Qore 0.8.8 added the full parameter

◆ listFiles() [1/2]

list<auto> Qore::Dir::listFiles ( bool  full = False)

Retrieves all files in this directory; if any errors occur an exception is thrown.

This method uses stat() system call internally to get info about directory entries. If a stat() call fails for a file, the file is skipped and information about this file is not included in the returned list.

Parameters
fullif True then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Returns
a list of all files in the current directory of the object; if full is True, then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Example:
try {
foreach string e in (d.listFiles()) {
printf("entry: %s\n");
}
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-READ-ERRORno directory is set
DIR-READ-FAILUREerror reading directory (arg will be assigned to the errno value)
Since
Qore 0.8.8 added the full parameter

◆ listFiles() [2/2]

list<auto> Qore::Dir::listFiles ( string  regex,
softint  regex_options = 0,
softbool  full = False 
)

Retrieves all files in the directory that match the given regular expression; if any errors occur an exception is thrown.

This method uses stat() system call internally to get info about directory entries. If a stat() call fails for a file, the file is skipped and information about this file is not included in the returned list.

Parameters
regexa regular expression string used to filter the arguments (note that this is not a glob, but rather a regular expression string)
regex_optionsoptional bitwise-or'ed regex option constants
fullif True then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Returns
a list of all files in the directory that match the given regular expression; if full is True, then the return value is a list of DirStatInfo hashes, otherwise a simple list of string names is returned
Example:
try {
foreach string e in (d.listFiles("\\.txt$")) {
printf("entry: %s\n");
}
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-READ-ERRORno directory is set
DIR-READ-FAILUREerror reading directory (arg will be assigned to the errno value)
REGEX-COMPILATION-ERRORerror in regular expression
REGEX-OPTION-ERRORregex option argument contains invalid option bits
Since
Qore 0.8.8 added the full parameter

◆ mkdir()

nothing Qore::Dir::mkdir ( string  subdir,
softint  mode = 0777 
)

Creates a direct subdirectory in the Dir object's current path.

Parameters
subdirThe subdirectory name to create; only direct subdirectories are allowed; directory separator characters are not allowed
modeThe mode of the directory
Example:
try {
dir.mkdir("subdir", 0750);
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-MKDIR-PARAMETER-ERRORonly direct subdirectories are allowed
DIR-MKDIR-FAILUREerror creating directory (arg will be assigned to the errno value)

◆ openDir()

Dir Qore::Dir::openDir ( string  subdir,
*string  encoding 
)

Get a Dir object as an subdir entry of the current directory.

Parameters
subdirThe name of the subdirectory for the new Dir object (which must be in the current directory of the current Dir object; no path separator characters are allowed)
encodingThe name of the default character encoding for the new Dir object; if this argument is not given, the new Dir object will be tagged with the character encoding of the current Dir object
Returns
The Dir object created for the directory
Example:
Dir sd = d.openDir("mysubdir");
Exceptions
DIR-OPENDIR-PARAMETER-ERRORonly direct subdirectory names without path separators are allowed

◆ openFile()

File Qore::Dir::openFile ( string  filename,
int  flags = O_RDONLY,
int  mode = 0666,
*string  encoding 
)

Create and open a File object in the current directory of the Dir object.

This method uses the File::open2() method to open the file.

Parameters
filenameThe filename for the file which must be in the current directory (no path separator characters are allowed)
flagsFlags that determine the way the file is accessed, see File Open Constants for more information
modePermission bits for when the file is to be created
encodingThe name of the default character encoding for this file; if this argument is not given, the file will be tagged with the default character encoding for the process
Example:
# open a file for writing in the directory and set the mode to 0644 and the encoding to UTF-8
File f = d.openFile("myfile.txt", O_CREAT|O_WRONLY, 0644, "utf-8");
Exceptions
DIR-OPENFILE-PARAMETER-ERRORonly direct subdirectory names without path separators are allowed
Note
see File::open2() for additional exceptions that can be thrown opening the file

◆ path()

*string Qore::Dir::path ( )

Returns the path of the Dir object or NOTHING if no path is set.

This path does not necessarily need to exist; the path is adjusted to remove "." and ".." from the path if present

Returns
the path of the Dir object or NOTHING if no path is set
Example:
*string mypath = d.path();

◆ removeFile()

bool Qore::Dir::removeFile ( string  file)

Remove the file with the given name in the Dir object's directory.

If any errors occur unlinking the file, then an exception occurs

Parameters
fileRemove the file with the given name in the Dir object's directory
Returns
True if the file was present and could be removed, False if the file did not exist
Example:
try {
bool b = dir.removeFile(filename);
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-REMOVEFILE-PARAMETER-ERRORonly filenames without path (i.e. without path separator characters) are allowed
DIR-REMOVEFILE-FAILUREthe unlink() function returned an error (arg will be assigned to the errno value)

◆ rmdir()

nothing Qore::Dir::rmdir ( string  subdir)

Removes a direct subdirectory from the Dir object's current path.

Parameters
subdirThe subdirectory name to remove; only direct subdirectories are allowed; directory separator characters are not allowed
Example:
try {
dir.rmdir("subdir");
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-RMDIR-PARAMETER-ERRORonly direct subdirectories are allowed
DIR-RMDIR-FAILUREerror removing directory (arg will be assigned to the errno value)
See also
Qore::rmdir()

◆ stat()

list<auto> Qore::Dir::stat ( )

Returns a list of file status information for the current directory.

If any errors occur an exception will be thrown

Returns
a Stat List giving information about the current directory
Example:
try {
list<auto> l = dir.stat();
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-STAT-ERRORno directory is set
DIR-STAT-FAILUREerror stat'ing directory (arg will be assigned to the errno value)

◆ statvfs()

hash<FilesystemInfo> Qore::Dir::statvfs ( )

Returns a FilesystemInfo hash for the current directory.

Returns
a FilesystemInfo hash for the current directory
Platform Availability:
Qore::Option::HAVE_STATVFS
Example:
try {
hash<FilesystemInfo> h = dir.statvfs();
} catch (hash<ExceptionInfo> ex) {
stderr.printf("%s: %s", ex.err, ex.desc);
}
Exceptions
DIR-STATVFS-ERRORno directory is set
DIR-STATVFS-FAILUREerror in statvfs (arg will be assigned to the errno value)