Qore::Dir Class Reference

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

## Public Member Functions

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 | list (bool full=False)
| Get all entries in this directory, except `"."` and `".."` directories; if any errors occur an exception is thrown. More...
list | 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 | listDirs (bool full=False)
| Retrieves all subdirectory entries in this directory, except `"."` and `".."` directories; if any errors occur an exception is thrown. More...
list | 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 | listFiles (bool full=False)
| Retrieves all files in this directory; if any errors occur an exception is thrown. More...
list | 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 | 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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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:
  try {
  if (!d.exists()) {
  printf("%y: does not exist; creating...\n", d.path());
  cnt = d.create(0755);
  }
  }
  catch (hash ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 Qore::Dir::list | ( | bool | full = `False` | ) |

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

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 ex) {
  stderr.printf("%s: %s", ex.err, ex.desc);
  if (ex.arg)
  stderr.printf(": %s", strerror(ex.arg));
  stderr.printf("\n");
  }

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

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 ex) {
  stderr.printf("%s: %s", ex.err, ex.desc);
  if (ex.arg)
  stderr.printf(": %s", strerror(ex.arg));
  stderr.printf("\n");
  }

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 Qore::Dir::listDirs | ( | bool | full = `False` | ) |

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

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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 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.

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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 Qore::Dir::listFiles | ( | bool | full = `False` | ) |

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

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 ex) {
  stderr.printf("%s: %s", ex.err, ex.desc);
  if (ex.arg)
  stderr.printf(": %s", strerror(ex.arg));
  stderr.printf("\n");
  }

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

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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 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 l = dir.stat();
  }
  catch (hash ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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 h = dir.statvfs();
  }
  catch (hash ex) {
  if (ex.arg)
  printf("%s: %s: %s", ex.err, ex.desc, strerror(ex.arg));
  else
  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)