DirectoryStream

DirectoryStream Class

The DirectoryStream class contains methods for creating and deleting directories, and for reading files in directories.

On machines which have library support for file globbing, DirectoryStream provides methods that read directories and files that match patterns which contain metacharacters like ‘*’, ‘?’, and ‘[’. This is in addition to whatever file pattern expansion the shell performs on file patterns provided on the command line. See below for more details.

Metacharacter Expansion.

If a command provides a file specification that contains a metacharacter, often the shell expands the pattern into a list of files that the program receives in the function main's argv array.

If the command line provides a quoted metacharacter as one of the program’s arguments, however, the program can use the DirectoryStream methods globPattern and globCwd to expand the pattern into a list of filenames.

$ myfileprog some_arg *    # The shell expands '*' into a list of files.

$ myfileprog some_arg '*'  # The shell adds a literal '*' to the app's
                           # arguments.

Not all shells provide metacharacter expansion before the program executes main, however, and so the app should check for metacharacters as arguments also. The following example shows one way to do this.

List new fileNames;

String instanceMethod globFile (void) {

  DirectoryStream new d;
  List new globFiles;

  if (d hasMeta self) {  /* The argv entry contains a wildcard character. */
    d globPattern self, globFiles;
    globFiles map {
      fileNames push self;
    }
  } else {             /* The argv entry is an unambiguous file name. */
    fileNames push self;
  }

}

int main (int argc, char *argv[]) {
  
  int i;

  for (i = 1; i < argc; ++i) {
    argv[i] globFile;
  }
  
  fileNames map {
    printf ("%s\n", self);
  }
}

Directory Modes

The default mode for new directories is 0755 (‘drwxr-xr-x’) modified by the user’s UMASK. Programs can change the default directory permissions by redefining the macro CTALK_DIRECTORY_MODE.

Error Handling

The methods chDir, mkDir, and rmDir raise a SystemErrnoException on error and return an Integer with the value -1.

Instance Methods

chDir (char *dir)

Change to the directory dir.

directoryList (char *dirname, List dirlist)

List directory dirname, and store it in the List dirlist. The order of the elements in the list depends on the operating system. To expressly create a sorted directory listing, see the sortedDirectoryList method.

getCwd (void)

Return the current directory as a String object.

globPattern (String file_name_pattern, List matching_file_names)

Adds the file names that match file_name_pattern to matching_file_names. This method uses the machine’s glob library call, if it is available, to do the pattern matching. If the system doesn’t support filename pattern matching in its C library, the method prints a warning message and returns. For more information about how the machine expands file globbing patterns into file names, refer to the glob(3) and glob(7) manual pages.

hasMeta (String file_name_pattern)

Returns a Boolean value of True if file_name_pattern contains one of the opening metacharacters ‘*’, ‘?’, or ‘[’, False otherwise.

mkDir (char *directoryname)

Create the directory directoryname.

rmDir (char *directoryname)

Delete the directory directoryname.

sortedDirectoryList (char *dirname, SortedList dirlist)

List directory dirname, and store it in the SortedList dirlist. The members of the directory listing are stored in ascending order.