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