Qore::Dir Class Reference

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

#include <QC_Dir.dox.h>

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< StatInfo >	hstat ()
	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< FilesystemInfo >	statvfs ()
	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

path	The 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-ERROR

cannot 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

gid	the 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-ERROR	cannot change directory owner; no directory is set
DIR-CHOWN-FAILURE	error 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

groupname

the 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-ERROR	no userid found for user
DIR-CHOWN-ERROR	cannot change directory owner; no directory is set
DIR-CHOWN-FAILURE	error 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

mode	The mode of the directory

Example:

try {
    dir.chmod(0750);
} catch (hash<ExceptionInfo> ex) {
    stderr.printf("%s: %s", ex.err, ex.desc);
}

Exceptions

DIR-CHMOD-ERROR	cannot change directory's mode; no directory is set
DIR-CHMOD-FAILURE	error 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

uid	the 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-ERROR	cannot change directory owner; no directory is set
DIR-CHOWN-FAILURE	error 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

username

the 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-ERROR	no userid found for user
DIR-CHOWN-ERROR	cannot change directory owner; no directory is set
DIR-CHOWN-FAILURE	error 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

encoding

the 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

mode	The 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);
    }
}

Exceptions

DIR-CREATE-ERROR	cannot create directory; no directory is set
DIR-CREATE-FAILURE	error 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-ERROR	no directory is set
DIR-HSTAT-FAILURE	error 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

full	if 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-ERROR	no directory is set
DIR-READ-FAILURE	error 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

regex	a regular expression string used to filter the arguments (note that this is not a glob, but rather a regular expression string)
regex_options	optional bitwise-or'ed regex option constants
full	if 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-ERROR	no directory is set
DIR-READ-FAILURE	error reading directory (arg will be assigned to the errno value)
REGEX-COMPILATION-ERROR	error in regular expression
REGEX-OPTION-ERROR	regex 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

full	if 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-ERROR	no directory is set
DIR-READ-FAILURE	error 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

regex	a regular expression string used to filter the arguments (note that this is not a glob, but rather a regular expression string)
regex_options	optional bitwise-or'ed regex option constants
full	if 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-ERROR	no directory is set
DIR-READ-FAILURE	error reading directory (arg will be assigned to the errno value)
REGEX-COMPILATION-ERROR	error in regular expression
REGEX-OPTION-ERROR	regex 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

full	if 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-ERROR	no directory is set
DIR-READ-FAILURE	error 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

regex	a regular expression string used to filter the arguments (note that this is not a glob, but rather a regular expression string)
regex_options	optional bitwise-or'ed regex option constants
full	if 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-ERROR	no directory is set
DIR-READ-FAILURE	error reading directory (arg will be assigned to the errno value)
REGEX-COMPILATION-ERROR	error in regular expression
REGEX-OPTION-ERROR	regex 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

subdir	The subdirectory name to create; only direct subdirectories are allowed; directory separator characters are not allowed
mode	The 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-ERROR	only direct subdirectories are allowed
DIR-MKDIR-FAILURE	error 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

subdir	The 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)
encoding	The 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-ERROR

only 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

filename	The filename for the file which must be in the current directory (no path separator characters are allowed)
flags	Flags that determine the way the file is accessed, see File Open Constants for more information
mode	Permission bits for when the file is to be created
encoding	The 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-ERROR

only 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

file	Remove 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-ERROR	only filenames without path (i.e. without path separator characters) are allowed
DIR-REMOVEFILE-FAILURE	the 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

subdir

The 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-ERROR	only direct subdirectories are allowed
DIR-RMDIR-FAILURE	error 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-ERROR	no directory is set
DIR-STAT-FAILURE	error 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-ERROR	no directory is set
DIR-STATVFS-FAILURE	error in statvfs (arg will be assigned to the errno value)