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 |
---|---|---|
N | Create a Directory object with the optional character encoding. It points to the directory the script is started. | |
N | Destroys the directory object. | |
N | Creates a new directory object with the same character encoding specification and the same path as the original. | |
N | Change the path of the directory. The path specification can be relative or absolute (with leading '/'). This path not necessarily needs to exist. | |
N | Return the current path of the object. The path is stripped of all '.' and '..' entries. | |
N | Checks if the path in the object is an openable directory. | |
Y | Try to create all directories of the object if they do not exist yet. | |
Y | Change the ownership of the directory to the given user. | |
Y | Change the group membership of the directory to the given group. | |
Y | Change the permissions of the directory to the given mode. | |
Y | Create a subdirectory with the name in the directory. | |
Y | Delete an empty subdirectory with the name in the directory. | |
Y | Get all entries in this directory, except '.' and '..' directories (takes an optional regular expression filter). | |
Y | Get all entries in the directory which are not subdirectories (takes an optional regular expression filter). | |
Y | Get all entries in the directory which are subdirectories, except '.' and '..' directories (takes an optional regular expression filter). | |
Y | Get a Dir object as an subdir entry of the current directory. | |
Y | Get a File object which represents a file in the directory. | |
Y | Remove (unlink) a file in this directory. |
Creates a Dir object. It accepts one optional argument that will set the default character encoding encoding for the directory.
new Dir([string:encoding]
)
$d = new Dir("UTF-8");
Table 4.153. Arguments for Dir::constructor()
Argument | Type | Description |
---|---|---|
| String | The character encoding for the directory. Any entry of the directory will be converted to this character encoding if necessary. |
Creates a new Dir object with the same character encoding specification and path as the original.
Dir::copy()
$d2 = $d.copy();
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. |
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.
Dir::chdir(newdir)
if($d.chdir("../doc")) { printf("the directory does not exist or is not readable\n"); }
Table 4.158. Return Value for Dir::chdir()
Return Type | Description |
---|---|
Boolean | True if the new path is openable as directory (see exists()). |
Return the path of the Dir object. This path needs not necessarily to exist. The path is stripped from all '.' and '..' directories.
Dir::path()
$mypath = $d.path();
Return if the path in the Dir object points to a directory which is openable by the Program.
Dir::exists()
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. |
Create the whole directory tree the Dir object points to, if it does not exist till now.
Dir::create([mode])
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.165. Exceptions Thrown by Dir::create()
err | desc |
---|---|
| One of the directories in the path could not be created. |
Change the ownership of the directory.
Dir::chown(uid|username)
$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 |
---|---|
| Parameter error. |
| The error occoured in the chown() call. |
Change the group membership of the directory.
Dir::chgrp(gid|groupname)
$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 |
---|---|
| Parameter error. |
| Error occoured during the change group chown() system call. |
Change the mode of the directory.
Dir::chmod([mode])
$d.chmod(0711); # set mode to u(rwx) and go(x)
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 |
---|---|
| Parameter error. |
| The error returned from the chmod() system call. |
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.
Dir::mkdir(subdir, [mode])
$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 |
---|---|
| Parameter error. |
| The error returned from the mkdir() system call. |
Remove a subdirectory from the Dir object's path. There is no pathinfo allowed in the name (the '/' delimiter).
Dir::rmdir(dirname)
$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 |
---|---|
| Parameter error. |
| The error returned from the rmdir() system call. |
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.
Dir::list([regex, [regex_option]])
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 |
---|---|
| The error returned from the readdir() system call. |
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.
Dir::listFiles()
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 |
---|---|
| The error returned from the readdir() system call. |
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.
Dir::listDirs()
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 |
---|---|
| The error returned from the readdir() system call. |
Return a Dir object in the directory of the Dir object. The dirname does not allow path information (the '/').
Dir::openDir(string:dirname, [string:charset]
)
# 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 |
---|---|---|
| String | The name of the subdirectory. The directory must not exist and can be created with create() afterwards. |
| 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 |
---|---|
| The directory name to be opened contains path information ('/'). |
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.
Dir::openFile(string:filename, [integer:flags, [integer:mode, [string:charset]]]
)
# 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 |
---|---|---|
| String | The Filename of the file. |
| 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. |
| Integer | Permission bits for when the file is to be created (default: 0666) |
| 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 |
---|---|
| The file name to be opened contains path information ('/'). |
File Exceptions | Exceptions thrown by the File::open2() call. |
Remove the file with the given name in the Dir object's directory.
Dir::removeFile(filename)
$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 |
---|---|
| Parameter error. |
| The error returned by the unlink() system call. |