4.4. Dir Class

4.4. Dir Class
Prev	Chapter 4. System Namespaces and Class Library	Next

Note: This class is not available with the PO_NO_FILESYSTEM parse option.

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 Qore character encoding is assumed.

Table 4.148. Dir Method Overview

Method	Except?	Description
`Dir::constructor()` `Dir::constructor(string$encoding)`	N	Create a Directory object with optional character encoding. It points to the directory the script is started.
`Dir::destructor()`	N	Destroys the directory object.
`Dir::copy()`	N	Creates a new directory object with the same character encoding specification and the same path as the original.
`boolDir::chdir(string$path)`	N	Change the path of the directory. The path specification can be relative or absolute (with leading '/'). This path does not necessarily need to exist.
`*stringDir::path()`	N	Returns a string giving the current path of the object, stripped of all '.' and '..' entries or NOTHING if no path is set.
`boolDir::exists()`	N	Checks if the path in the object is an openable directory.
`intDir::create(softint$mode = 0777)`	Y	Try to create all directories of the object if they do not exist yet; if any errors occur an exception is thrown.
`nothingDir::chown(softint$uid)` `nothingDir::chown(string$username)`	Y	Change the ownership of the directory to the given user.
`nothingDir::chgrp(softint$gid)` `nothingDir::chgrp(string$groupname)`	Y	Change the group membership of the directory to the given group.
`nothingDir::chmod(softint$mode)`	Y	Change the permissions of the directory to the given mode; if any errors occur an exception is thrown.
`hashDir::hstat()`	Y	Returns a Stat Hash about the directory's status or throws an exception if any errors occur.
`nothingDir::mkdir(string$name, softint$mode = 0777)`	Y	Create a subdirectory with the name in the directory; if any errors occur an exception is thrown.
`nothingDir::rmdir(string$subdir)`	Y	Delete an empty subdirectory with the name in the directory; if any errors occur an exception is thrown.
`listFile::stat()`	Y	Returns a Stat List about the directory's status or throws an exception if any errors occur.
`hashDir::statvfs()`	Y	Returns a Filesystem Status Hash about the directory's filesystem status or throws an exception if any errors occur.
`listDir::list()` `listDir::list(string$regex)` `listDir::list(string$regex, int$options)`	Y	Get all entries in this directory, except '.' and '..' directories (takes an optional regular expression filter); if any errors occur an exception is thrown.
`listDir::listFiles()` `listDir::listFiles(string$regex)` `listDir::listFiles(string$regex, int$options)`	Y	Get all entries in the directory which are not subdirectories (takes an optional regular expression filter); if any errors occur an exception is thrown.
`listDir::listDirs()` `listDir::listDirs(string$regex)` `listDir::listDirs(string$regex, int$options)`	Y	Get all entries in the directory which are subdirectories, except '.' and '..' directories (takes an optional regular expression filter); if any errors occur an exception is thrown.
`DirDir::openDir(string$subdir)` `DirDir::openDir(string$subdir, string$encoding)`	Y	Get a Dir object as an subdir entry of the current directory.
`FileDir::openFile(string$name, softint$flags = O_RDONLY, softint$mode = 0666)` `FileDir::openFile(string$name, softint$flags = O_RDONLY, softint$mode = 0666, string$encoding)`	Y	Get a File object which represents a file in the directory.
`boolDir::removeFile(string$name)`	Y	Remove (unlink) a file in this directory.

4.4.1. Dir::constructor()

Synopsis

Creates a Dir object. It accepts one optional argument that will set the default character encoding encoding for the directory.

Prototype

Dir::constructor()

Dir::constructor(string$encoding)

Example

my Dir $d("UTF-8");

Table 4.149. Arguments for Dir::constructor()

Argument	Description
`[string$encoding`	The character encoding for the directory. Any entry of the directory will be converted to this character encoding if necessary, and entries read will be tagged with this encoding. If no encoding is given, the default encoding is used.

4.4.2. Dir::destructor()

Synopsis

Destroys the Dir object.

Example

delete $d;

4.4.3. Dir::copy()

Synopsis

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

Example

my Dir $d2 = $d.copy();

4.4.4. Dir::chdir()

Synopsis

Change the directory of the Dir object to the path; you can use either an absolute path (leading with '/') or a directory realtive to the actual path.

Prototype

boolDir::chdir(string$path)

Example

if ($d.chdir("../doc")) {
   printf("the directory does not exist or is not readable\n");
}

Table 4.150. Arguments for Dir::chdir()

Argument	Description
`string$path`	The new directory name.

Table 4.151. Return Value for Dir::chdir()

Return Type	Description
`bool`	True if the new path is openable as directory (see exists()).

4.4.5. Dir::path()

Synopsis

Return the path of the Dir object or NOTHING if no path is set. This path does not necessarily need to exist. '.' and '..' str stripped from the path if present.

Prototype

*stringDir::path()

Example

my *string $mypath = $d.path();

Table 4.152. Return Value for Dir::path()

Return Type	Description
`*string`	The path of the Dir object or NOTHING if no path is set.

4.4.6. Dir::exists()

Synopsis

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

Prototype

boolDir::exists()

Example

if (!$d.exists()) {
   printf("the directory %s does not exist or cannot be opened\n", $d.path());
   exit(-1);
}

Table 4.153. Return Value for Dir::exists()

Return Type	Description
`bool`	True if the directory exists and is openable.

4.4.7. Dir::create()

Synopsis

Create the whole directory tree the Dir object points to, if it does not exist till now.

Prototype

intDir::create(softint$mode = 0777)

Example

if (!$d.exists()) {
   printf("directory '%s' does not exist; creating...\n", $d.path());
   $cnt = $d.create();
}

Table 4.154. Arguments for Dir::create()

Argument	Description
`softint$mode = 0777`	The mode of the directory.

Table 4.155. Return Value for Dir::create()

Return Type	Description
`int`	Number directories created.

Table 4.156. Exceptions Thrown by Dir::create()

err	desc
`DIR-CREATE-ERROR`	One of the directories in the path could not be created.

4.4.8. Dir::chown()

Synopsis

Change the ownership of the directory.

Prototype

nothingDir::chown(softint$uid)

nothingDir::chown(string$username)

Example

$d.chown("nobody");

Platform Availability

HAVE_UNIX_FILEMGT

Table 4.157. Arguments for Dir::chown()

Argument	Description
`softint$uid`	The userid to be used.
`string$username`	A username which is known by the system.

Table 4.158. Exceptions Thrown by Dir::chown()

err	desc
`DIR-CHOWN-PARAMETER-ERROR`	Parameter error.
`DIR-CHOWN-ERROR`	The error occoured in the chown() call.
`MISSING-FEATURE-ERROR`	This exception is thrown when the method is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_FILEMGT` before calling this function.

4.4.9. Dir::chgrp()

Synopsis

Change the group membership of the directory.

Prototype

nothingDir::chgrp(softint$gid)

nothingDir::chgrp(string$groupname)

Example

$d.chgrp("nogroup");

Platform Availability

HAVE_UNIX_FILEMGT

Table 4.159. Arguments for Dir::chgrp()

Argument	Description
`softint$gid`	The groupid to be set for the directory.
`string$groupname`	The name of the group to be set. Must be known in the system.

Table 4.160. Exceptions Thrown by Dir::chgrp()

err	desc
`DIR-CHGRP-PARAMETER-ERROR`	Parameter error.
`DIR-CHGRP-ERROR`	Error occoured during the change group chown() system call.
`MISSING-FEATURE-ERROR`	This exception is thrown when the method is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_FILEMGT` before calling this function.

4.4.10. Dir::chmod()

Synopsis

Change the mode of the directory.

Prototype

nothingDir::chmod(softint$mode)

Example

$d.chmod(0711); # set mode to u(rwx) and go(x)

Table 4.161. Arguments for Dir::chmod()

Argument	Description
`softint$mode`	The mode of the directory.

Table 4.162. Exceptions Thrown by Dir::chmod()

err	desc
`DIR-CHMOD-ERROR`	The error returned from the chmod() system call.

4.4.11. Dir::hstat()

Synopsis

Returns a hash of directory status values for the current directory.

If any errors occur, a DIR-HSTAT-ERROR exception is thrown.

Prototype

hashDir::hstat()

Example

my hash $h = $dir.hstat();

Table 4.163. Return Values for Dir::hstat()

Return Type	Description
`hash`	Returns a hash of directory status values for the current directory (must be set); if any errors occur, an exception is thrown. See Stat Hash for a description of the hash returned by this method.

Table 4.164. Exceptions Thrown by Dir::hstat()

err	desc
`DIR-HSTAT-ERROR`	`stat()` call failed or no directory name set.

4.4.12. Dir::mkdir()

Synopsis

Make a subdirectory in the Dir object's path. There are no path info allowed (the '/'). If no mode is given the mode 0777 is used.

Prototype

nothingDir::mkdir(string$name, softint$mode = 0777)

Example

$d.mkdir("newSubDir", 0755);

Table 4.165. Arguments for Dir::mkdir()

Argument	Description
`string$name, softint$mode = 0777`	The name and mode of the subdirectory.

Table 4.166. Exceptions Thrown by Dir:mkdir()

err	desc
`DIR-MKDIR-PARAMETER-ERROR`	Parameter error.
`DIR-MKDIR-ERROR`	The error returned from the mkdir() system call.

4.4.13. Dir::rmdir()

Synopsis

Remove a subdirectory from the Dir object's path. There is no pathinfo allowed in the name (the '/' delimiter).

Prototype

nothingDir::rmdir(string$subdir)

Example

$d.rmdir("emptySubdir");

Table 4.167. Arguments for Dir::rmdir()

Argument	Description
`string$subdir`	The name of the directory to be removed.

Table 4.168. Exceptions Thrown by Dir::rmdir()

err	desc
`DIR-RMDIR-PARAMETER-ERROR`	Parameter error.
`DIR-RMDIR-ERROR`	The error returned from the rmdir() system call.

4.4.14. Dir::stat()

Synopsis

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

If any errors occur, a DIR-STAT-ERROR exception is thrown.

Return Type	Description
`list`	Returns a list of status values for the current directory; an exception is thrown if any errors occur. See Stat List below for a description of the list returned by this method.

err	desc
`DIR-STAT-ERROR`	`stat()` call failed or directory not set.

4.4.15. Dir::statvfs()

Synopsis

Returns a hash of filesystem status values for the current directory.

If any errors occur, a DIR-STATVFS-ERROR exception is thrown.

Return Type	Description
`hash`	Returns a hash of filesystem status values current file; an exception is thrown if any errors occur. See also static File::statvfs(). See Filesystem Status Hash for a description of the hash returned by this function.

err	desc
`DIR-STATVFS-ERROR`	`statvfs()` call failed or directory name is not set.
`MISSING-FEATURE-ERROR`	This exception is thrown when the method is not available on the runtime platform; for maximum portability, check the constant `HAVE_STATVFS` before calling this function.

4.4.16. Dir::list()

Synopsis

List all entries in the directory of the Dir object. It supresses the '.' and '..' directory. An optional regular expression string can be passed to filter the values returned; if this argument is given then only entries that match the regular expression will be returned.

Prototype

listDir::list()

listDir::list(string$regex)

listDir::list(string$regex, int$options)

Example

foreachmy string $e in ($d.list()) {
   printf("entry: %s\n");
}

Table 4.173. Arguments for Dir::list()

Argument	Description
`[string$regex, [int$options]]`	An optional regular expression string used to filter the arguments followed by bitwise-or'ed regex option constants.

Table 4.174. Return Value for Dir::list()

Return Type	Description
list	A list of Strings with the directories content.

Table 4.175. Exceptions Thrown by Dir::list()

err	desc
`DIR-READ-ERROR`	The error returned from the readdir() system call.

4.4.17. Dir::listFiles()

Synopsis

List all entries in the directory of the Dir object, which are not subdirectories. An optional regular expression string can be passed to filter the values returned; if this argument is given then only entries that match the regular expression will be returned.

Prototype

listDir::listFiles()

listDir::listFiles(string$regex)

listDir::listFiles(string$regex, int$options)

Example

foreachmy string $e in ($d.listFiles()) {
   printf("entry: %s\n");
}

Table 4.176. Arguments for Dir::listFiles()

Argument	Description
`[string$regex, [int$options]]`	An optional regular expression string used to filter the arguments followed by bitwise-or'ed regex option constants.

Table 4.177. Return Value for Dir::listFiles()

Return Type	Description
list	A list of strings with the file names as elements.

Table 4.178. Exceptions Thrown by Dir::listFiles()

err	desc
`DIR-READ-ERROR`	The error returned from the readdir() system call.

4.4.18. Dir::listDirs()

Synopsis

List all entries in the directory of the Dir object that are subdirectories, not including the '.' and '..' directories. An optional regular expression string can be passed to filter the values returned; if this argument is given then only entries that match the regular expression will be returned.

Prototype

listDir::listDirs()

listDir::listDirs(string$regex)

listDir::listDirs(string$regex, int$options)

Example

foreachmy string $e in ($d.listDirs()) {
   printf("entry: %s\n");
}

Table 4.179. Arguments for Dir::listDirs()

Argument	Description
`[string$regex, [int$options]]`	An optional regular expression string used to filter the arguments followed by bitwise-or'ed regex option constants.

Table 4.180. Return Value for Dir::listDirs()

Return Type	Description
list	A list of strings with the directory names found.

Table 4.181. Exceptions Thrown by Dir::listDirs()

err	desc
`DIR-READ-ERROR`	The error returned from the readdir() system call.

4.4.19. Dir::openDir()

Synopsis

Return a Dir object in the directory of the Dir object. The dirname does not allow path information (the '/').

Prototype

DirDir::openDir(string$subdir)

DirDir::openDir(string$subdir, string$encoding)

Example

# open a subdir for working with
my Dir $sd = $d.openDir("mysubdir", "ISO-8859-1");
my list $sd_list = $sd.list();

Table 4.182. Arguments for Dir::openDir()

Argument	Description
`string$subdir, [string$encoding]`	The name of the subdirectory. The directory must not exist and can be created with create() afterwards. If no encoding is given, the default encoding is used.

Table 4.183. Return Value for Dir::openDir()

Return Type	Description
`Dir`	The Dir object created for the directory.

Table 4.184. Exceptions Thrown by Dir::openDir()

err	desc
`DIR-OPENDIR-PARAMETER-ERROR`	The directory name to be opened contains path information ('/').

4.4.20. Dir::openFile()

Synopsis

Create or open a File object in the directory of the Dir object. The filename does not allow path information (the '/'). Uses the File::open2() method.

Prototype

FileDir::openFile(string$name, softint$flags = O_RDONLY, softint$mode = 0666)

FileDir::openFile(string$name, softint$flags = O_RDONLY, softint$mode = 0666, string$encoding)

Example

# open a file for writing in the directory and set the mode to
# 0644 and the encoding to UTF-8
my $f = $d.openFile("myfile.txt", O_CREAT|O_WRONLY, 0644, "UTF-8");

Table 4.185. Arguments for Dir::openFile()

Argument	Description
`stringname`	The name of the file in the current directory.
`softint$flags = O_RDONLY`	Flags that determine the way the file is accessed, see File Constants for more information. If this argument is not given, `O_RDONLY` will be used as the default value.
`softint$mode = 0666`	Permission bits for when the file is to be created (default: 0666)
`[string$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.

Table 4.186. Return Value for Dir::openFile()

Return Type	Description
Object	The File object created or opened in the directory.

Table 4.187. Exceptions Thrown by Dir::openFile()

err	desc
`DIR-OPENFILE-PARAMETER-ERROR`	The file name to be opened contains path information ('/').
File Exceptions	Exceptions thrown by the File::open2() call.

4.4.21. Dir::removeFile()

Synopsis

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

Prototype

boolDir::removeFile(string$name)

Example

$d.removeFile("myTestFile.dat");

Table 4.188. Arguments for Dir::removeFile()

Argument	Description
`string$name`	The name of the file in the directory.

Table 4.189. Return Value for Dir::removeFile()

Return Type	Description
`bool`	True if the file was present and could be removed. `False` if the file did not exist. If any errors occur unlinking an existing file, then an exception occurs.

Table 4.190. Exceptions Thrown by Dir::removeFile()

err	desc
`DIR-REMOVEFILE-PARAMETER-ERROR`	Parameter error.
`DIR-REMOVEFILE-ERROR`	The error returned by the unlink() system call.

Prev	Up	Next
4.3. File Class	Home	4.5. TermIOS Class