4.4. Dir Class

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.152. Dir Method Overview

Method

Except?

Description

Dir::constructor()

N

Create a Directory object with the 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.

Dir::chdir()

N

Change the path of the directory. The path specification can be relative or absolute (with leading '/'). This path not necessarily needs to exist.

Dir::path()

N

Return the current path of the object. The path is stripped of all '.' and '..' entries.

Dir::exists()

N

Checks if the path in the object is an openable directory.

Dir::create()

Y

Try to create all directories of the object if they do not exist yet.

Dir::chown()

Y

Change the ownership of the directory to the given user.

Dir::chgrp()

Y

Change the group membership of the directory to the given group.

Dir::chmod()

Y

Change the permissions of the directory to the given mode.

Dir::mkdir()

Y

Create a subdirectory with the name in the directory.

Dir::rmdir()

Y

Delete an empty subdirectory with the name in the directory.

Dir::list()

Y

Get all entries in this directory, except '.' and '..' directories (takes an optional regular expression filter).

Dir::listFiles()

Y

Get all entries in the directory which are not subdirectories (takes an optional regular expression filter).

Dir::listDirs()

Y

Get all entries in the directory which are subdirectories, except '.' and '..' directories (takes an optional regular expression filter).

Dir::openDir()

Y

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

Dir::openFile()

Y

Get a File object which represents a file in the directory.

Dir::removeFile()

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.

Usage
new Dir([string:encoding])
Example
$d = new Dir("UTF-8");

Table 4.153. Arguments for Dir::constructor()

Argument

Type

Description

encoding

String

The character encoding for the directory. Any entry of the directory will be converted to this character encoding if necessary.


Table 4.154. Return Value for Dir::constructor()

Return Type

Description

Object

The Dir object created.


4.4.2. Dir::destructor()

Synopsis

Destroys the Dir object.

Usage
delete lvalue
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.

Usage
Dir::copy()
Example
$d2 = $d.copy();

Table 4.155. Arguments for Dir::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.156. Return Value for Dir::copy()

Return Type

Description

n/a

The new Dir object created with the same character encoding specification and path as the original object.


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.

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

Table 4.157. Arguments for Dir::chdir()

Argument

Type

Description

newdir

String

The new directory name.


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

Return Type

Description

Boolean

True if the new path is openable as directory (see exists()).


4.4.5. Dir::path()

Synopsis

Return the path of the Dir object. This path needs not necessarily to exist. The path is stripped from all '.' and '..' directories.

Usage
Dir::path()
Example
$mypath = $d.path();

Table 4.159. Arguments for Dir::path()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

String

The path of the Dir object.


4.4.6. Dir::exists()

Synopsis

Return if the path in the Dir object points to a directory which is openable by the Program.

Usage
Dir::exists()
Example
if(!$d.exists()) {
  printf("the directory %s does not exist\n", $d.path());
  exit(-1);
}
            

Table 4.161. Arguments for Dir::exists()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Boolean

True if the directory 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.

Usage
Dir::create([mode])
Example
if (!$d.exists()) {
  printf("directory '%s' does not exist, so i create it\n", $d.path());
  $cnt = $d.create();
}
            

Table 4.163. Arguments for Dir::create()

Argument

Type

Description

[mode]

Integer

The mode of the directory.


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

Return Type

Description

Integer

Number directories created.


Table 4.165. 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.

Usage
Dir::chown(uid|username)
Example
$d.chown("nobody");
            

Table 4.166. Arguments for Dir::chown()

Argument

Type

Description

uid

Integer

The userid to be used.

username

String

A username which is known by the system.


Table 4.167. Return Value for Dir::chown()

Return Type

Description

n/a

This method does not return any value.


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

err

desc

DIR-CHOWN-PARAMETER-ERROR

Parameter error.

DIR-CHOWN-ERROR

The error occoured in the chown() call.


4.4.9. Dir::chgrp()

Synopsis

Change the group membership of the directory.

Usage
Dir::chgrp(gid|groupname)
Example
$d.chgrp("nogroup");
            

Table 4.169. Arguments for Dir::chgrp()

Argument

Type

Description

gid

Integer

The groupid to be set for the directory.

groupname

String

The name of the group to be set. Must be known in the system.


Table 4.170. Return Value for Dir::chgrp()

Return Type

Description

n/a

This method does not return any value.


Table 4.171. 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.


4.4.10. Dir::chmod()

Synopsis

Change the mode of the directory.

Usage
Dir::chmod([mode])
Example
$d.chmod(0711); # set mode to u(rwx) and go(x)
            

Table 4.172. Arguments for Dir::chmod()

Argument

Type

Description

mode

Integer

The mode of the directory.


Table 4.173. Return Value for Dir::chmod()

Return Type

Description

n/a

This method does not return any value.


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

err

desc

DIR-CHMOD-PARAMETER-ERROR

Parameter error.

DIR-CHMOD-ERROR

The error returned from the chmod() system call.


4.4.11. 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.

Usage
Dir::mkdir(subdir, [mode])
Example
$d.mkdir("newSubDir", 0755);
            

Table 4.175. Arguments for Dir::mkdir()

Argument

Type

Description

subdir

String

The name of the subdirectory.

mode

Integer

The mode of the new directory.


Table 4.176. Return Value for Dir::mkdir()

Return Type

Description

n/a

This method does not return any value.


Table 4.177. 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.12. Dir::rmdir()

Synopsis

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

Usage
Dir::rmdir(dirname)
Example
$d.rmdir("emptySubdir");
            

Table 4.178. Arguments for Dir::rmdir()

Argument

Type

Description

dirname

String

The name of the directory to be removed.


Table 4.179. Return Value for Dir::rmdir()

Return Type

Description

n/a

This method does not return any value.


Table 4.180. 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.13. 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.

Usage
Dir::list([regex, [regex_option]])
Example
foreach my $e in ( $d.list() ) {
  printf("entry: %s\n");
}
            

Table 4.181. Arguments for Dir::list()

Argument

Type

Description

[regex]

string

A regular expression string used to filter the arguments.

[regex_option]

Integer

For valid options, see Regex Constants


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

Return Type

Description

List

A list of Strings with the directories content.


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

err

desc

DIR-READ-ERROR

The error returned from the readdir() system call.


4.4.14. 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.

Usage
Dir::listFiles()
Example
foreach my $e in ( $d.listFiles() ) {
  printf("file: %s\n");
}
            

Table 4.184. Arguments for Dir::listFiles()

Argument

Type

Description

[regex]

string

A regular expression string used to filter the arguments.

[regex_option]

Integer

For valid options, see Regex Constants


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

Return Type

Description

List

A list of Strings with the directories content.


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

err

desc

DIR-READ-ERROR

The error returned from the readdir() system call.


4.4.15. Dir::listDirs()

Synopsis

List all entries in the directory of the Dir object, which are subdirectories. It supresses 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.

Usage
Dir::listDirs()
Example
foreach my $e in ( $d.listDirs() ) {
  printf("entry: %s\n");
}
            

Table 4.187. Arguments for Dir::listDirs()

Argument

Type

Description

[regex]

string

A regular expression string used to filter the arguments.

[regex_option]

Integer

For valid options, see Regex Constants


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

Return Type

Description

List

A list of Strings with the directories content.


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

err

desc

DIR-READ-ERROR

The error returned from the readdir() system call.


4.4.16. Dir::openDir()

Synopsis

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

Usage
Dir::openDir(string:dirname, [string:charset])
Example
# open a subdir for working with.
$sd = $d.openDir("mysubdir", "ISO-8859-1");
$sd_list = $sd.list();
            

Table 4.190. Arguments for Dir::openDir()

Argument

Type

Description

dirname

String

The name of the subdirectory. The directory must not exist and can be created with create() afterwards.

charset

String

The name of the default character encoding for this directory.


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

Return Type

Description

Object

The Dir object created for the directory.


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

err

desc

DIR-OPENDIR-PARAMETER-ERROR

The directory name to be opened contains path information ('/').


4.4.17. 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.

Usage
Dir::openFile(string:filename, [integer:flags, [integer:mode, [string:charset]]])
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.193. Arguments for Dir::openFile()

Argument

Type

Description

filename

String

The Filename of the file.

flags

Integer

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.

mode

Integer

Permission bits for when the file is to be created (default: 0666)

charset

String

The name of the default character encoding for this file.


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

Return Type

Description

Object

The File object created or opened in the directory.


Table 4.195. 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.18. Dir::removeFile()

Synopsis

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

Usage
Dir::removeFile(filename)
Example
$d.removeFile("myTestFile.dat");
            

Table 4.196. Arguments for Dir::removeFile()

Argument

Type

Description

filename

String

The name of the file in the directory.


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

Return Type

Description

Boolean

True if the file was present and could be removed. False if the file did not exist.


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

err

desc

DIR-REMOVEFILE-PARAMETER-ERROR

Parameter error.

DIR-REMOVEFILE-ERROR

The error returned by the unlink() system call.