The FILE_SEARCH function returns a string array containing the names of all files matching the input path specification. Input path specifications may contain wildcard characters, enabling them to match multiple files. A relative path is a file path that can only be unambiguously interpreted by basing it relative to some other known location. Usually, this location is the current working directory for the process. A fully qualified path is a complete and unambiguous path that can be interpreted directly. For example, bin/idl is a relative path, while /usr/local/rsi/idl/bin/idl is a fully qualified path. By default, FILE_SEARCH follows the format of the input to decide whether to return relative or fully-qualified paths.
The wildcards understood by FILE_SEARCH are based on those used by standard UNIX tools. They are described in Supported Wildcards and Expansions.
| Note |
The wildcards understood by FILE_SEARCH are based on those used by the standard UNIX shell /bin/sh (the ?, *, [, and ], characters, and environment variables) with some enhancements commonly found in the C-shell /bin/csh (the ~, {, and } characters). These wildcards are processed identically across all IDL supported platforms. The supported wildcards are shown in the following table:
These wildcards can appear anywhere in an input file specification, with the following exceptions:
The tilde character is only considered to be a wildcard if it is the first character in the input file specification and the EXPAND_TILDE keyword is set. Otherwise, it is treated as a regular character.
On a local area network, Microsoft Windows offers an alternative to the drive letter syntax for accessing files. The Universal Naming Convention (UNC) allows for specification of paths on other hosts using the syntax:
\\hostname\sharename\dir\dir\...\file
UNC paths are distinguished from normal paths by the use of two initial slashes in the path. FILE_SEARCH can process such paths, but wildcard characters are not allowed in the hostname or sharename segments. Wildcards are allowed for specifying directories and files. For performance reasons, RSI does not recommend using the recursive form of FILE_SEARCH with UNC paths on very large directory trees.
When using FILE_SEARCH, you should be aware of the following issues:
The default is for wildcards not to match the dot (.) character if it occurs as the first character of a directory or file name. This follows the convention of UNIX shells, which treat such names as hidden files. In order to match such files, you can take any of the following actions:
The syntax allowed for file paths differs between operating systems. FILE_SEARCH always processes file paths using the syntax rules for the platform on which the IDL session is running. As a convenience for Microsoft Windows users, Windows IDL accepts UNIX style forward slashes as well as the usual backslashes as path separators.
The different operating systems supported by IDL have some conventions for processing file paths that are inherently incompatible. If FILE_SEARCH attempted to force an identical default policy for these features across all platforms, the resulting routine would be inconvenient to use on all platforms. FILE_SEARCH resolves this inherent tension between convenience and control in the following way:
The keywords that have different defaults on different platforms are listed in the following table:
|
Wildcard
|
Keyword
|
Default
UNIX |
Default
Win |
|---|---|---|---|
|
$var
${var} ${var:-alttext} ${var-alttext} |
EXPAND_ENVIRONMENT
|
yes
|
no
|
|
~
|
EXPAND_TILDE
|
yes
|
no
|
| |
FOLD_CASE
|
no
|
yes
|
Result = FILE_SEARCH(Path_Specification)
or for recursive searching,
Result = FILE_SEARCH(Dir_Specification, Recur_Pattern)
Keywords: [, COUNT=variable ] [, /EXPAND_ENVIRONMENT ] [, /EXPAND_TILDE ] [, /FOLD_CASE ] [, /FULLY_QUALIFY_PATH ] [, /ISSUE_ACCESS_ERROR ] [, /MARK_DIRECTORY ] [, /MATCH_INITIAL_DOT | /MATCH_ALL_INITIAL_DOT ] [, /NOSORT ] [, /QUOTE ] [, /TEST_DIRECTORY ] [, /TEST_EXECUTABLE ] [, /TEST_READ ] [, /TEST_REGULAR ] [, /TEST_WRITE ] [, /TEST_ZERO_LENGTH ]
UNIX-Only Keywords: [, /TEST_BLOCK_SPECIAL ] [, /TEST_CHARACTER_SPECIAL ] [, /TEST_DANGLING_SYMLINK ] [, /TEST_GROUP ] [, /TEST_NAMED_PIPE ] [, /TEST_SETGID ] [, /TEST_SETUID ] [, /TEST_SOCKET ] [, /TEST_STICKY_BIT ] [, /TEST_SYMLINK ] [, /TEST_USER ]
Returns all matched filenames in a string array, one file name per array element. If no files exist with names matching the input arguments, a null scalar string is returned instead of a string array.
If the input path is relative, the results will be relative. If the input is fully qualified, the results will also be fully qualified. If you specify the FULLY_QUALIFY_PATH keyword, the results will be fully qualified no matter which form of input is used. FILE_SEARCH returns results based on standard and recursive searches:
find(1) command.
| Note |
Any of the arguments described in this section can contain wildcard characters, as described in Supported Wildcards and Expansions.
A scalar or array variable of string type, containing file paths to match. If Path_Specification is not supplied, or if it is supplied as a null string, FILE_SEARCH uses a default pattern of '*', which matches all files in the current directory.
A scalar or array variable of string type, containing directory paths within which FILE_SEARCH will perform recursive searching for files matching the Recur_Pattern argument. FILE_SEARCH examines Dir_Specification, and any directory found below it, and returns the paths of any files in those directories that match Recur_Pattern. If Dir_Specification is supplied as a null string, FILE_SEARCH searches the current directory.
A scalar string containing a pattern for files to match in any of the directories specified by the Dir_Specification argument. If Recur_Pattern is supplied as a null string, FILE_SEARCH uses a default pattern of '*', which matches all files in the specified directories.
A named variable into which the number of files found is placed. If no files are found, a value of 0 (zero) is returned.
By default, FILE_SEARCH follows the conventions of the underlying operating system to determine whether it should expand environment variable references in input file specification patterns. The default is to do such expansions under UNIX, and not to do them under Microsoft Windows. The EXPAND_ENVIRONMENT keyword is used to change this behavior. Set it to a non-zero value to cause FILE_SEARCH to perform environment variable expansion on all platforms. Set it to zero to disable such expansion.
The syntax for expanding environment variables in an input file pattern is based on that supported by the standard UNIX shell (/bin/sh), as described in Supported Wildcards and Expansions.
Users of the UNIX C-shell (/bin/csh), and other tools influenced by it, are familiar with the use of a tilde (~) character at the beginning of a path to denote a home directory. A tilde by itself at the beginning of the path (e.g. ~/directory/file) is equivalent to the home directory of the user executing the command, while a tilde followed by the name of a user (e.g. ~user/directory/file) is expanded to the home directory of the named user.
By default, FILE_SEARCH follows the conventions of the underlying operating system in deciding whether to expand a leading tilde or to treat it as a literal character. Hence, the default is to expand the leading tilde under UNIX, and not under Microsoft Windows. The EXPAND_TILDE keyword is used to change this behavior.
Set EXPAND_TILDE to 0 (zero) to disable tilde expansion on all platforms. Set it to a non-zero value to enable tilde expansion.
| Note |
By default, FILE_SEARCH follows the case sensitivity policy of the underlying operating system. By default, matches are case sensitive on UNIX platforms, and case insensitive on Microsoft Windows platforms. The FOLD_CASE keyword is used to change this behavior. Set it to a non-zero value to cause FILE_SEARCH to do all file matching case insensitively. Explicitly set FOLD_CASE equal to zero to cause all file matching to be case sensitive.
RSI does not recommend changing the default value of FOLD_CASE, for the following reasons:
.dat extension without regard to the case of the extension:
datafiles = FILE_SEARCH('*.dat', /FOLD_CASE)
If set, FILE_SEARCH expands all returned file paths so that they are complete. Under UNIX, this means that all files are specified relative to the root of the file system. On Windows platforms, it means that all files are specified relative to the drive on which they are located. By default, FILE_SEARCH returns fully qualified paths when the input specification is fully qualified, and returns relative paths otherwise. For example:
CD, '/usr/local/rsi/idl/bin'
PRINT, FILE_SEARCH('idl')
idl
PRINT, FILE_SEARCH('idl',/FULLY_QUALIFY_PATH)
/usr/local/rsi/idl/bin/idl
Under Microsoft Windows, any use of a drive letter colon (:) character implies full qualification, even if the path following the colon does not start with a slash character.
If the IDL process lacks the necessary permission to access a directory included in the input specification, FILE_SEARCH will normally skip over it quietly and not include it in the generated results. Set ISSUE_ACCESS_ERROR to cause an error to be issued instead.
If set, all directory paths are returned with a path separator character appended to the end. This allows the caller to concatenate a file name directly to the end without having to supply a separator character first. This is convenient for cross-platform programming, as the separator characters differ between operating systems:
PRINT, FILE_SEARCH(!DIR) /usr/local/rsi/idl PRINT, FILE_SEARCH(!DIR, /MARK_DIRECTORY) /usr/local/rsi/idl/
By default, wildcards do not match leading dot (.) characters, and FILE_SEARCH does not return the names of files that start with the dot (.) character unless the leading dot is actually contained within the search string. Set MATCH_ALL_INITIAL_DOT to change this policy so that wildcards will match all files starting with a dot, including the special "." (current directory) and ".." (parent directory) entries. RSI recommends the use of the MATCH_INITIAL_DOT keyword instead of MATCH_ALL_INITIAL_DOT for most purposes.
MATCH_INITIAL_DOT serves the same function as MATCH_ALL_INITIAL_DOT, except that the special "." (current directory) and ".." (parent directory) directories are not included.
If set, FILE_SEARCH will not sort the list of files returned by the operating system. On some operating systems, particularly UNIX, this can make FILE_SEARCH execute faster. Under Microsoft Windows, setting NOSORT has no effect, since the operating system returns a sorted list of files to IDL.
FILE_SEARCH usually treats all wildcards found in the input specification as having the special meanings described in Supported Wildcards and Expansions. This means that such characters cannot normally be used as plain literal characters in file names. For example, it is not possible to match a file that contains a literal asterisk character in its name because asterisk is interpreted as the "match zero or more characters" wildcard.
If the QUOTE keyword is set, the backslash character can be used to escape any character so that it is treated as a plain character with no special meaning. In this mode, FILE_SEARCH replaces any two-character sequence starting with a backslash with the second character of the pair. In the process, any special wildcard meaning that character might have had disappears, and the character is treated as a literal.
If QUOTE is set, any literal backslash characters in your path must themselves be escaped with a backslash character. This is especially important for Microsoft Windows users, because the directory separator character for that platform is the backslash. Windows IDL also accepts UNIX-style forward slashes for directory separators, so Windows users have two choices in handling this issue:
Result = FILE_SEARCH('C:\\home\\bob\\\*.dat', /QUOTE)
Result = FILE_SEARCH('C:/home/bob/\*.dat', /QUOTE)
On a Windows system, either of these options gives the path to a file named *.dat.
Only include a matching file if it is a block special device.
Only include a matching file if it is a character special device.
Only include a matching file if it is a symbolic link that points at a non-existent file.
Only include a matching file if it is a directory.
Only include a matching file if it is executable. The source of this information differs between operating systems:
UNIX: IDL checks the per-file information (the execute bit) maintained by the operating system.
Microsoft Windows: The determination is made on the basis of the file name extension (e.g. .exe).
Only include a matching file if it belongs to the same effective group ID (GID) as the IDL process.
Only include a matching file if it is a named pipe (fifo) device.
Only include a matching file if it is readable by the user.
| Note |
Only include a matching file if it is a regular disk file and not a directory, pipe, socket, or other special file type.
Only include a matching file if it has its Set-Group-ID bit set.
Only include a matching file if it has its Set-User-ID bit set.
Only include a matching file if it is a UNIX domain socket.
Only include a matching file if it has its sticky bit set.
Only include a matching file if it is a symbolic link that points at an existing file.
Only include a matching file if it belongs to the same effective user ID (UID) as the IDL process.
Only include a matching file if it is writable by the user.
| Note |
Only include a matching file if it has zero length.
| Note |
The keywords with names that start with the TEST_ prefix allow you to filter the list of resulting file paths based on various criteria. If you remove the TEST_ prefix from these keywords, they correspond directly to the same keywords to the FILE_TEST function, and are internally implemented by the same test code. One could therefore use FILE_TEST instead of the TEST_ keywords to FILE_SEARCH. For example, the following statement locates all subdirectories of the current directory:
Result = FILE_SEARCH(/TEST_DIRECTORY)
It is equivalent to the following statements, using FILE_TEST:
result = FILE_SEARCH() idx = where(FILE_TEST(result, /DIRECTORY), count) result = (count eq 0) ? '' : result[idx]
The TEST_* keywords are more succinct, and can be more efficient in the common case in which FILE_SEARCH generates a long list of results, only to have FILE_TEST discard most of them.
Find all files in the current working directory:
Result = FILE_SEARCH()
Find all IDL program (*.pro) files in the current working directory:
Result = FILE_SEARCH('*.pro')
Under Microsoft Windows, find all files in the top level directories of all drives other than the floppy drives:
Result=FILE_SEARCH('[!ab]:*')
This example relies on the following:
Find all files in the user's home directory that start with the letters A-D. Match both upper and lowercase letters:
Result = FILE_SEARCH('~/[a-d]*', /EXPAND_TILDE, /FOLD_CASE)
Find all directories in the user's home directory that start with the letters A-D. Match both upper and lowercase letters:
Result = FILE_SEARCH('~/[a-d]*', /EXPAND_TILDE, /FOLD_CASE, $
/TEST_DIRECTORY)
Recursively find all subdirectories found underneath the user's home directory that do not start with a dot character:
Result = FILE_SEARCH('$HOME', '*', /EXPAND_ENVIRONMENT, $
/TEST_DIRECTORY)
Recursively find all subdirectories found underneath the user's home directory, including those that start with a dot character, but excluding the special "." and ".." directories:
Result = FILE_SEARCH('$HOME', '*', /MATCH_INITIAL_DOT, $
/EXPAND_ENVIRONMENT, /TEST_DIRECTORY)
Find all .pro and .sav files in an IDL library search path, sorted by directory, in the order IDL searches for them:
Result = FILE_SEARCH(STRSPLIT(!PATH, PATH_SEP(/SEARCH_PATH), $ /EXTRACT) + '/*.{pro,sav}')
Colon (:) is the UNIX path separator character, so the call to STRSPLIT breaks the IDL search path into an array of directories. To each directory name, we concatenate the wildcards necessary to match any .pro or .sav files in that directory. When this array is passed to FILE_SEARCH, it locates all files that match these specifications. FILE_SEARCH sorts all of the files found by each input string. The files for each string are then placed into the output array in the order they were searched for.
Recursively find all directories in your IDL distribution:
Result = FILE_SEARCH(!DIR, '*', /TEST_DIRECTORY)
Introduced: 5.5
FILE_TEST, FILEPATH, FINDFILE, GETENV