IDL provides a variety of routines that allow you to retrieve information about and manipulate files and directories.
IDL file handling routines are listed in the following table:
The FILE_SEARCH function returns an array of strings containing the names of all files that match its argument string. The argument string may contain any wildcard characters understood by the command interpreter. For example, to determine the number of IDL procedure files that exist in the current directory, use the following statement:
PRINT, '# IDL pro files:',N_ELEMENTS(FILE_SEARCH('*.pro'))
See FILE_SEARCH for details.
The FILE_CHMOD procedure allows you to change the current access permissions (also referred to as modes) associated with a file or directory. File modes are specified using the standard Posix convention of three protection classes (user, group, other), each containing three attributes (read, write, execute). This is the same format familiar to users of the UNIX chmod(1) command. For example, to make the file moose.dat read-only to everyone except the owner of the file, but otherwise not change any other settings:
FILE_CHMOD, 'moose.dat', /u_write, g_write=0, o_write=0
To make the file be readable and writable to the owner and group, but read-only to anyone else, and remove any other modes:
FILE_CHMOD, 'moose.dat', '664'
To find the current protection settings for a given file, you can use the GET_MODE keyword to the FILE_TEST function.
See FILE_CHMOD for details.
The FILE_COPY procedure allows you to copy files and directories from one location to another. The copies retain the protection settings of the original files, and belong to the user that performed the copy.
See FILE_COPY for details.
The FILE_MOVE procedure allows you to rename files and directories. The moved files retain their protection and ownership attributes. Within a given file system or volume, FILE_MOVE does not copy file data. Rather, it simply changes the file names by updating the directory structure of the file system.
See FILE_MOVE for details.
The FILE_DELETE procedure allows you to delete files and empty directories for which they have appropriate permission. The process must have the necessary permissions to remove the file, as defined by the current operating system. FILE_CHMOD can be used to change file protection settings.
Microsoft Windows users should be careful to not specify a trailing backslash at the end of a specification. For example:
FILE_DELETE, 'c:\mydir\myfile'
and not:
FILE_DELETE, 'c:\mydir\myfile\'
See FILE_DELETE for details.
The FILE_EXPAND_PATH function can be used with a given a file or directory name to convert the name to its fully qualified form and return it. A fully-qualified file path completely specifies the location of a file without the need to consider the user's current working directory.
| Note |
A = FILE_EXPAND_PATH(FILE_SEARCH('*.pro'))
Alternatively, you can use the FULLY_QUALIFY_PATH keyword to FILE_SEARCH:
A = FILE_SEARCH('*.pro', /FULLY_QUALIFY_PATH)See FILE_EXPAND_PATH for details.
You can create a directory using the FILE_MKDIR procedure. The resulting directory or directories are created with default access permissions for the current process. If needed, you can use the FILE_CHMOD procedure to alter access permissions. If a specified directory has non-existent parent directories, FILE_MKDIR automatically creates all the intermediate directories as well. For instance, to create a subdirectory named moose in the current working directory:
FILE_MKDIR, 'moose'
See FILE_MKDIR for details.
The FILE_TEST function allows you to determine if a file exists without having to open it. Additionally, using the FILE_TEST keywords provides information about the file's attributes. For example, to determine whether your IDL distribution supports the SGI IRIX operating system:
result = FILE_TEST(!DIR + '/bin/bin.sgi', /DIRECTORY) PRINT, 'SGI IDL Installed: ', result ? 'yes' : 'no'
See FILE_TEST for details.
The FILE_WHICH function separates a specified file path into its component directories, and searches each directory in turn. If a directory contains the file, the full name of that file including the directory path is returned. If FILE_WHICH does not find the desired file, a NULL string is returned.
This command is modeled after the UNIX which(1) command, but is written in the IDL language and is available on all platforms. Its source code can be found in the file file_which.pro in the lib subdirectory of the IDL distribution.
As an example, the following line of code allows you to find the location of the file_which.pro file:
Result = FILE_WHICH('file_which.pro')
Alternately, to find the location of the UNIX ls command:
Result = FILE_WHICH(getenv('PATH'), 'ls')
See FILE_WHICH for details.
On UNIX platforms, you can create file links, both regular (hard) and symbolic. A hard link is a directory entry that references a file. UNIX allows multiple such links to exist simultaneously, meaning that a given file can be referenced by multiple names. The following limitations on hard links are enforced by the operating system:
A symbolic link is an indirect pointer to a file; its directory entry contains the name of the file to which it is linked. Symbolic links may span file systems and may refer to directories.
Use the FILE_LINK procedure to create hard and soft links on UNIX systems. See FILE_LINK for details.
Use the FILE_READLINK procedure to retrieve the path to a file referenced by a UNIX symbolic link. See FILE_READLINK for details.
Use the FILE_SAME function to determine whether two file names refer to the same underlying file. See FILE_SAME for details.
Information about currently open file units is available by using the FILES keyword with the HELP procedure. If no arguments are provided, information about all currently open user file units (units 1-128) is given. For example, the following command can be used to get information about the three special units (-2, -1, and 0):
HELP, /FILES, -2, -1, 0
This command results in output similar to the following:
Unit Attributes Name -2 Write, New, Tty, Reserved <stderr> -1 Write, New, Tty, Reserved <stdout> 0 Read, Tty, Reserved <stdin>
See HELP for details.
You can use the FILE_INFO function to retrieve information about a file that is not currently open (that is, for which there is no IDL Logical Unit Number available). To get information about an open file, use the FSTAT function.
The FILE_INFO function returns a structure expression of type FILE_INFO containing information about the file. For example, use to get information on the file dist.pro within the IDL User Library:
HELP,/STRUCTURE, FILE_INFO(FILEPATH('dist.pro', $
SUBDIRECTORY = 'lib'))
The above command will produce output similar to:
** Structure FILE_INFO, 21 tags, length=72:
NAME STRING '/usr/local/rsi/idl/lib/dist.pro'
EXISTS BYTE 1
READ BYTE 1
WRITE BYTE 0
EXECUTE BYTE 0
REGULAR BYTE 1
DIRECTORY BYTE 0
BLOCK_SPECIAL BYTE 0
CHARACTER_SPECIAL
BYTE 0
NAMED_PIPE BYTE 0
SETGID BYTE 0
SETUID BYTE 0
SOCKET BYTE 0
STICKY_BIT BYTE 0
SYMLINK BYTE 0
DANGLING_SYMLINK
BYTE 0
MODE LONG 420
ATIME LONG64 970241431
CTIME LONG64 970241595
MTIME LONG64 969980845
SIZE LONG64 1717
The fields of the FILE_INFO structure provide various information about the file, such as the size of the file, and the dates of last access, creation, and last modification. For more information on the fields of the FILE_INFO structure, see FILE_INFO.
Use the FILE_LINES function to retrieve the number of lines of text in a file. See FILE_LINES for details.
The FSTAT function can be used to retrieve information about a file that is currently open (that is, for which there is an IDL Logical Unit Number available). It returns a structure expression of type FSTAT or FSTAT64 containing information about the file. For example, to get detailed information about the standard input, use the following command:
HELP, /STRUCTURES, FSTAT(0)
This displays the following information:
** Structure FSTAT, 17 tags, length=64: UNIT LONG 0 NAME STRING '<stdin>' OPEN BYTE 1 ISATTY BYTE 0 ISAGUI BYTE 1 INTERACTIVE BYTE 1 XDR BYTE 0 COMPRESS BYTE 0 READ BYTE 1 wWRITE BYTE 0 ATIME LONG64 0 CTIME LONG64 0 MTIME LONG64 0 TRANSFER_COUNT LONG 0 CUR_PTR LONG 0 SIZE LONG 0 REC_LEN LONG 0
On some platforms, IDL can support files that are longer than 2^31-1 bytes in length. If FSTAT is applied to such a file, it returns an expression of type FSTAT64 instead of the FSTAT structure shown above. FSTAT64 differs from FSTAT only in that the TRANSFER_COUNT, CUR_PTR, SIZE, and REC_LEN fields are signed 64-bit integers (type LONG64) in order to be able to represent the larger sizes.
The fields of the FSTAT and FSTAT64 structures provide various information about the file, such as the size of the file, and the dates of last access, creation, and last modification. For more information on the fields of the FSTAT and FSTAT64 structures, see FSTAT.
The following IDL function can be used to read single-precision, floating-point data from a stream file into a vector when the number of elements in the file is not known. It uses the FSTAT function to get the size of the file in bytes and divides by four (the size of a single-precision, floating-point value) to determine the number of values.
;READ_DATA reads all the floating point values from a stream file ;and returns the result as a floating-point vector. FUNCTION READ_DATA, file ;Get a unique file unit and open the data file. OPENR, /GET_LUN, unit, file ;Get file status. status = FSTAT(unit) ;Make an array to hold the input data. The SIZE field of status ;gives the number of bytes in the file, and single-precision, ;floating-point values are four bytes each. data = FLTARR(status.size / 4) ;Read the data. READU, unit, data ;Deallocate the file unit. The file also will be closed. FREE_LUN, unit RETURN, data END
Assuming that a file named data.dat exists and contains 10 floating-point values, the READ_DATA function could be used as follows:
;Read floating-point values from data.dat.
A = READ_DATA('data.dat')
;Show the result.
HELP, A
The following output is produced:
A FLOAT = Array(10)
For efficiency, IDL buffers its input/output in memory. Therefore, when data are output, there is a window of time during which data are in memory and have not been actually placed into the file. Normally, this behavior is transparent to the user (except for the improved performance). The FLUSH routine exists for those rare occasions where a program needs to be certain that the data has actually been written to the file immediately. For example, use the statement,
FLUSH, 1
to flush file unit one.
See FLUSH for details.
Each open file unit has a current file pointer associated with it. This file pointer indicates the position in the file at which the next input/output operation will take place. The file position is specified as the number of bytes from the start of the file. The first position in the file is position zero. The following statement will rewind file unit 1 to its start:
POINT_LUN, 1, 0
The following sequence of statements will position it at the end of the file:
tmp = FSTAT(1) POINT_LUN, 1, tmp.size
POINT_LUN has the following operating-system specific behavior:
See POINT_LUN for details.
The EOF function is used to test a file unit to see if it is currently positioned at the end of the file. It returns true (1) if the end-of-file condition is true and false (0) otherwise.
For example, to read the contents of a file and print it on the screen, use the following statements:
;Open file demo.doc for reading. OPENR, 1, 'demo.doc' ;Create a variable of type string. LINE = '' ;Read and print each line until the end of the file is encountered. WHILE(~ EOF(1)) DO BEGIN READF,1,LINE & PRINT,LINE & END ;Done with the file. CLOSE, 1
See EOF for details.
The GET_KBRD function returns the next character available from the standard input (IDL file unit zero) as a single character string. It takes a single parameter named WAIT. If WAIT is zero, the function returns the null string if there are no characters in the terminal typeahead buffer. If it is nonzero, the function waits for a character to be typed before returning.
Under Windows, the GET_KBRD function can be used to return Windows special characters (in addition to the standard keyboard characters). To get a special character, hold down the Alt key and type the character's ANSI equivalent on the numeric keypad while GET_KBRD is waiting. Control + key combinations are not supported.
See GET_KBRD for details.
| Note |
A procedure that updates the screen and exits when the carriage return is typed might appear as follows:
;Procedure definition.
PRO UPDATE, ...
;Loop forever.
WHILE 1 DO BEGIN
;Update screen here...
...
;Read character, no wait.
CASE GET_KBRD(0) OF
;Process letter A.
'A': ....
;Process letter B.
'B': ....
;Process other alternatives.
...
;Exit on carriage return (ASCII code = 15 octal).
STRING("15B): RETURN
;Ignore all other characters.
ELSE:
ENDCASE
ENDWHILE
;End of procedure.
END
The STRING function is very similar to the PRINT and PRINTF procedures. It can be thought of as a version of PRINT that places its formatted output into a string variable instead of a file. If the output is a single line, the result is a scalar string. If the output has multiple lines, the result is a string array with each element of the array containing a single line of the output.
The IDL statements:
;Produce a string array.
A=STRING(FORMAT='("The values are:", /, (I))', INDGEN(5))
;Show its structure.
HELP, A
;Print out the result.
FOR I = 0, 5 DO PRINT, A[I]
produce the following output:
A STRING = Array(6) The values are: 0 1 2 3 4
See STRING for details.
The READS procedure performs formatted input from a string variable and writes the results into one or more output variables. This procedure differs from the READ procedure only in that the input comes from memory instead of a file.
This routine is useful when you need to examine the format of a data file before reading the information it contains. Each line of the file can be read into a string using READF. Then the components of that line can be read into variables using READS.
See the description of READS for more details.