FSTAT

The FSTAT function returns a structure expression of type FSTAT containing status information about a specified file unit. The contents of this structure are documented in The FSTAT Function .

Fields of the FSTAT Structure

The following descriptions are of fields in the structure returned by the FSTAT function. They are not keywords to FSTAT.

UNIT

The IDL logical unit number (LUN).

NAME

The name of the file.

OPEN

Nonzero if the file unit is open. If OPEN is zero, the remaining fields in FSTAT will not contain useful information.

ISATTY

Nonzero if the file is actually a terminal instead of a normal file. For example, if you are using an xterm window on a Unix system and you invoke FSTAT on logical unit 0 (standard input), ISATTY will be set to 1.

ISAGUI

Nonzero if the file is actually a Graphical User Interface (for example, a logical unit associated with the IDL Development Environment). Thus, if you are using the IDLDE and you invoke FSTAT on logical unit 0 (standard input), ISAGUI will be set to 1.

INTERACTIVE

Nonzero if either ISATTY or ISAGUI is nonzero.

READ

Nonzero if the file is open for read access.

WRITE

Nonzero if the file is open for write access.

TRANSFER_COUNT

The number of scalar IDL data items transferred in the last input/output operation on the unit. This is set by the following IDL routines: READU, WRITEU, PRINT, PRINTF, READ, and READF. TRANSFER_COUNT is useful when attempting to recover from input/output errors.

CUR_PTR

The current position of the file pointer, given in bytes from the start of the file. If the device is a terminal (ISATTY is nonzero), the value of CUR_PTR will not contain useful information.

SIZE

The current length of the file in bytes. If the device is a terminal (ISATTY is nonzero), the value of SIZE will not contain useful information.

CAUTION: VMS variable length records have a 2-byte record-length descriptor at the beginning of each record. Because the SIZE field contains the length of the data file including the record descriptors, reading a file with VMS variable length records into a byte array of the size returned by FSTAT will result in an RMS EOF error.

REC_LEN

If the file is record-oriented (VMS), this field contains the record length; otherwise, it is zero.

Examples

If file unit number 1 is open, the FSTAT information on that unit can be seen by entering:

PRINT, FSTAT(1)

Specific information can be obtained by referring to single fields within the structure returned by FSTAT. The following code prints the name and length of the file open on unit 1:

A = FSTAT(1) ; Put FSTAT information in variable A.

PRINT, 'File: ', A.NAME, ' is ', A.SIZE, ' bytes long.'
; Print the name and size fields.