33.22. $directory

$directory finds the list of files contained in the directory named directoryName and places one file name in each element of fileNames. directoryName is expected to be in the same format as returned by $currentDirectory. If it is the null STRING, $currentDirectory is used. $directory returns FALSE if it cannot find or read the directory named directoryName, TRUE otherwise. The ARRAY fileNames is NULLARRAY if there are no files in the directory. directoryName may contain a device MODULE prefix, if appropriate.

If the operating system or device considers that subdirectories of a directory are files in that directory, the names of the subdirectories are also included in fileNames.

Valid ctrlBits are errorOK, $reportAllVersions, $fullPathNames, $useOriginalFileName, and $sorted. If $fullPathNames is set, fileNames contains full path names, i.e., file names that may be used from any directory; normally it contains only relative path names, i.e., file names that may be used when directoryName is the current directory. The $reportAllVersions bit is ignored except on operating systems or device MODULEs that maintain multiple numbered versions of files. On such systems or devices, only the most recent version of a file is included by default in the fileNames ARRAY, and the version number is not returned as part of a file name. If $reportAllVersions is set, however, all existing versions of a file are included, and the version number is included in the file name. If $useOriginalFileName is set, no logical name lookup or application of searchpaths is done; directoryName is used as specified. errorOK suppresses any system-dependent error message that might otherwise occur. If $sorted is set, the files in the produced ARRAY are sorted according to the usual (case-sensitive) STRING ordering, the first STRING at element 1, and the last at the upper bound of the ARRAY.

If you call $directory for a device MODULE other than the default (by including a device prefix in directoryName), the device MODULE name is prefixed to the file names in the fileNames ARRAY if and only if $fullPathNames is set in the ctrlBits parameter.

33.22.1. Transforming a Directory Name into a Relative Path Name

$composePath("",s,devModStr)

(where devModStr is the device prefix included in directoryName in the original call to $directory; it may be the empty STRING if there was no device prefix) or get the relative path name of a file name with base b and extension e in that directory by:

$composeFileName(b,e,devModStr,
        $composePath("",s,devModStr,$omitDevModStr))