Returning Information About a File Unit

Information about currently open file units is available by using the FILES keyword with the HELP procedure, or using the FSTAT function. 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" (IDL Reference Guide) for details.

Using FSTAT

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" (IDL Reference Guide).

An Example Using 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)