FSTAT

The FSTAT function returns status information about a specified file unit.

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:

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

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

Syntax

Result = FSTAT(Unit)

Return Value

The FSTAT function returns a structure expression of type FSTAT (or FSTAT64 in the case of files that are longer than 2^31-1 bytes in length) containing status information about a specified file unit.

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.

FSTAT Field Value

Description

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 Workbench). Thus, if you are using the workbench 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.

XDR

Nonzero if the file was opened with the XDR keyword, and is therefore considered to contain data in the XDR format.

COMPRESS

Nonzero if the file was opened with the COMPRESS keyword, and is therefore considered to contain compressed data in the GZIP format.

READ

Nonzero if the file is open for read access.

WRITE

Nonzero if the file is open for write access.

ATIME, CTIME, MTIME

The date of last access, date of file status change, and date of last modification given in seconds since 1 January 1970 UTC. Use the SYSTIME function to convert these dates into a textual representation. On Windows platforms the CTIME field will contain the file creation time. On Unix platforms the CTIME field will contain the time of the last file status change.

Note: Some file systems do not maintain all of these dates (e.g. MS DOS FAT file systems), and may return 0. On some non-UNIX operating systems, access time is not maintained, and ATIME and MTIME will always return the same date.

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. When reporting on file units opened with the COMPRESS keyword to OPEN, the position reported by CUR_PTR is the “logical” position—the position it would be at in the uncompressed version of the same file.

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. When reporting on file units opened with the COMPRESS keyword to OPEN, the size reported by SIZE is the compressed size of the actual file, and not the logical length of the uncompressed data contained within. This is inconsistent with the position reported by CUR_PTR. The reason for reporting the size in this way is that the logical length of the data cannot be known without reading the entire file from beginning to end and counting the uncompressed bytes, and this would be extremely inefficient.

REC_LEN

This field is obsolete and will always contain zero.

Arguments

Unit

The file unit about which information is required. This parameter can be an integer or an associated variable, in which case information about the variable’s associated file is returned.

Keywords

None.

Version History

Original

Introduced

See Also

ASSOCFILE_INFOFILE_TESTOPENR/OPENU/OPENW,General File Access