Routines (alphabetical) > Routines: F > FILE_TEST

# FILE_TEST

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