File Information

IDL maintains a file table in which it keeps a file descriptor for each file opened with IDL_FileOpen(). This table is indexed by the file Logical Unit Number, or LUN. These are the same LUNs IDL users use.

The IDL_FileStat() function is used to get information about a file.

IDL_FileStat()

void IDL_FileStat(int unit, IDL_FILE_STAT *stat_blk)

unit

The logical unit number (LUN) of the file unit to be checked. This function should only be called on file units that are known to be open.

stat_blk

A pointer to an IDL_FILE_STAT struct to be filled in with information about the file. The information returned is valid only as long as the file remains open. You must not access the fields of an IDL_FILE_STAT once the file it refers to has been closed. This struct has the definition:

typedef struct {

char *name;

short access;

IDL_SFILE_FLAGS_T flags;

FILE *fptr;

} IDL_FILE_STAT;

The fields of this struct are listed below:

name

A pointer to a null-terminated string containing the name the file was opened with.

access

A bit mask describing the access allowed to the file. The allowed bit values are:

• IDL_OPEN_R: The file is open for input.
• IDL_OPEN_W: The file is open for output.
• IDL_OPEN_TRUNC: The file was truncated when it was opened. This implies that IDL_OPEN_W is also set.
• IDL_OPEN_APND: The file was opened with the file pointer set just past the last byte of data in the file (the file is open for appending).

flags

A bit mask that gives special information about the file. The defined bits are:

• IDL_F_ISATTY: The file is a terminal.
• IDL_F_ISAGUI: The file is a Graphical User Interface.
• IDL_F_NOCLOSE: The CLOSE command will refuse to close the file.
• IDL_F_MORE: If the file is a terminal, output is sent through a pager similar to the UNIX more command. Details on this pager are not included in this document, and it is therefore not available for general use.
• IDL_F_XDR: The file is read/written using XDR (eXternal Data Representation).
• IDL_F_DEL_ON_CLOSE: The file will be deleted when it is closed.
• IDL_F_SR: The file is a SAVE/RESTORE file.
• IDL_F_SWAP_ENDIAN: The file has opposite byte order than that of the current system.
• IDL_F_VAX_FLOAT: Binary float and double are in VAX F and D format.
• IDL_F_COMPRESS: The file is in compressed gzip format. If IDL_F_SR is set (the file is a SAVE/RESTORE file), the file contains zlib compressed data.
• IDL_F_UNIX_F77: The file is read/written in the format used by the UNIX Fortran (f77) compiler for unformatted binary data.
• IDL_F_PIPE: The file is a bi-directional data path connecting IDL to a child process created by the SPAWN procedure.
• IDL_F_UNIX_RAWIO: No application level buffering will be performed for the file and all data transfers will go directly to the operating system for processing (e.g. read() and write() system calls under UNIX, Windows system-level API for MS Windows). Note that setting this bit does not guarantee that data will be written to the file immediately, because the operating system may buffer the data. This bit value was formerly called IDL_F_UNIX_NOSTDIO. IDL_F_UNIX_RAWIO is the preferred form, but both names are supported.
• IDL_F_UNIX_SPECIAL: The file is a UNIX device special file such as a pipe. This differs from IDL_F_PIPE because it applies to any file, not only those opened with the SPAWN procedure.
• IDL_F_STDIO: Use the C standard I/O library (stdio) to perform I/O on this file instead of any other native OS API that might be otherwise used. People intending to access IDL files via their own code should specify this flag if they intend to access the file from their external code as a stdio stream.
• IDL_F_SOCKET: File is an internet TCP/IP socket.

fptr

The stdio stream file pointer to the file. This field can be used with standard library functions to perform I/O. This field is always valid, although you shouldn’t use it if the file is an XDR file. You can check for this by looking for the IDL_F_XDR bit in the flags field.

If the file is not opened with the IDL_F_STDIO flag, fptr may be returned as an unusable NULL pointer, reflecting the fact that IDL is not using stdio to perform I/O on the file. If access to a valid fptr is important to your application, you should be sure to specify IDL_F_STDIO to the extra_flags argument to IDL_FileOpen, or use the STDIO keyword to OPEN if opening the file from the IDL user level.

In addition to the requirement to set the IDL_F_STDIO flag, note that IDL buffers I/O at a layer above the stdio package. If your code does I/O directly to a file that is also being written to from the IDL user level, the IDL buffer may cause data to be written to the file in a different order than you expect. There are several approaches you can take to prevent this:

• Tell IDL not to buffer, by opening the file from the IDL user level and specifying a value of -1 to the BUFSIZE keyword.
• Disable stdio buffering by calling the stdio setbuf() function.
• Ensure that you flush IDL’s buffer before you do any Input/Output, as discussed in Flushing Buffered Data.