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:
A = FSTAT(1)
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
See Also
ASSOC, FILE_INFO, FILE_TEST, OPENR/OPENU/OPENW,General File Access