The FILE_TEST function checks files for existence and other attributes without having to first open the file.

Examples


To determine whether your IDL distribution supports the Intel-based Mac operating system:

result = FILE_TEST(!DIR + '/bin/bin.darwin.i386', /DIRECTORY) 
PRINT, 'Intel-Mac Installed: ', result ? 'yes' : 'no'

Syntax


Result = FILE_TEST( File [, /DIRECTORY | ,  /EXECUTABLE | , /READ | , /REGULAR | ,  /WRITE | , /ZERO_LENGTH] [, GET_MODE=variable] [, /NOEXPAND_PATH] )

UNIX-Only Keywords: [, /BLOCK_SPECIAL | , /CHARACTER_SPECIAL | , /DANGLING_SYMLINK | , /GROUP | , /NAMED_PIPE | , /SETGID | , /SETUID | , /SOCKET | , /STICKY_BIT | , /SYMLINK | , /USER]

Return Value


FILE_TEST returns 1 (true), if the specified file exists and all of the attributes specified by the keywords are also true. If no keywords are present, a simple test for existence is performed. If the file does not exist or one of the specified attributes is not true, then FILE_TEST returns 0 (false).

Arguments


File

A scalar or array of file names to be tested. The result is of type integer with the same number of elements as File.

Note: Windows platforms have a file name length limit of 260 characters, while Unix platforms have a limit of 1024 characters. File names longer than this limit will return 0 (false).

Keywords


BLOCK_SPECIAL

This keyword is only available on UNIX platforms.

Set this keyword to return 1 (true) if File exists and is a block special device.

CHARACTER_SPECIAL

This keyword is only available on UNIX platforms.

Set this keyword to return 1 (true) if File exists and is a character special device.

DANGLING_SYMLINK

This keyword is only available on UNIX platforms.

Set this keyword to return 1 (true) if File is a symbolic link that points at a non-existent file.

DIRECTORY

Set this keyword to return 1 (true) if File exists and is a directory.

EXECUTABLE

Set this keyword to return 1 (true) if File exists and 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).

GET_MODE

Set this keyword to a named variable to receive the UNIX style mode (permission) mask for the specified file. The bits in these masks correspond to those used by the UNIX chmod(2) system call, and are explained in detail in the description of the Mode argument to the FILE_CHMOD procedure. When interpreting the value returned by this keyword, the following platform specific details should be kept in mind:

  • The setuid, setgid, and sticky bits are specific to the UNIX operating system, and will never be returned on any other platform. Consult the chmod(2) man page and/or other UNIX programming documentation for more details.
  • The Microsoft Windows operating system does not have 3 permission classes like UNIX does. Therefore, IDL returns the same settings for all three classes.
  • The Microsoft Windows operating system does not maintain an execute bit for files, but instead uses the file suffix to decide if a file is executable.

GROUP

This keyword is only available on UNIX platforms.

Set this keyword to return 1 (true) if File exists and belongs to the same effective group ID (GID) as the IDL process.

NAMED_PIPE

This keyword is only available on UNIX platforms.

Set this keyword to return 1 (true) if File exists and is a named pipe (fifo) device.

NOEXPAND_PATH

Set this keyword to cause FILE_TEST to use the File argument exactly as specified, without applying the usual file path expansion.

READ

Set this keyword to return 1 (true) if File exists and is readable by the user.

REGULAR

Set this keyword to return 1 (true) if File exists and is a regular disk file and not a directory, pipe, socket, or other special file type.

SETGID

This keyword is only available on UNIX platforms.

Set this keyword to return 1 (true) if File exists and has its Set-Group-ID bit set.

SETUID

This keyword is only available on UNIX platforms.

Set this keyword to return 1 (true) if File exists and has its Set-User-ID bit set.

SOCKET

This keyword is only available on UNIX platforms.

Set this keyword to return 1 (true) if File exists and is a UNIX domain socket.

STICKY_BIT

This keyword is only available on UNIX platforms.

Set this keyword to return 1 (true) if File exists and has its sticky bit set.

SYMLINK

This keyword is only available on UNIX platforms.

Set this keyword to return 1 (true) if File exists and is a symbolic link that points at an existing file.

USER

This keyword is only available on UNIX platforms.

Set this keyword to return 1 (true) if File exists and belongs to the same effective user ID (UID) as the IDL process.

WRITE

Set this keyword to return 1 (true) if File exists and is writable by the user.

ZERO_LENGTH

Set this keyword to return 1 (true) if File exists and has zero length.

Note: The length of a directory is highly system dependent and does not necessarily correspond to the number of files it contains. In particular, it is possible for an empty directory to report a non-zero length. Avoid using the ZERO_LENGTH keyword on directories, as the information returned cannot be used in a meaningful way.

                

Version History


5.4

Introduced

See Also


FILE_INFO,  FILE_SEARCH,  FSTAT, General File Access