35.4. $fileInfo

$fileInfo returns information about a file, given its name or an open file POINTER to it. NULLPOINTER is returned if the requested file cannot be found or if no information about the file can be obtained. Fields unavailable from the operating system are Zero, except that $OSDsize is -1L if unavailable, since 0L is a possible file length. The meanings of the fields of $fileInfoCls are as follows:

If the fileName argument to $fileInfo includes a device prefix, a device prefix is included in $fullPathName; otherwise, no device prefix appears in $fullPathName. If the device prefix in fileName specifies the format of a disk file (e.g., BS, VAR, FIX), the device prefix in $fullPathName is changed if the actual format of the file is different from that specified; e.g., if fileName is bs>foo, the prefix for $fullPathName may be var if foo is actually a VAR-format file.

If fi is Zero, a new record is allocated and a POINTER to it returned (if $fileInfo is successful; otherwise, $fileInfo returns NULLPOINTER). If fi is non-Zero, the record it points to is filled in and returned if $fileInfo is successful.

The exact value of $OSDSize is dependent on the device or operating system. It does not have any predictable relationship to the MAINSAIL end-of-file position. $OSDSize is intended to be used by programs that need to organize a list of files in approximate order of size.

The following bits are used in $fileAttr:

$bsFormat
$fixFormat
$varFormat
$isDirectory
$hasFileVersions

At most one of $bsFormat, $fixFormat, $varFormat, and $isDirectory can be set in $fileAttr. $bsFormat, $fixFormat, and $varFormat indicate byte-stream, fixed-length-record, and variable-length-record text and data files, respectively (for operating systems that support record-structured files, the MAINSAIL facilities used to access them are described in the appropriate system-specific MAINSAIL documentation). $isDirectory is set if the file is a directory. If the attributes of the file cannot be determined (or if $fileAttr has not yet been implemented on the device or operating system), none of these bits is set in $fileAttr.

$hasFileVersions may be set in $fileAttr Info if the device on which the file resides has file versions.

The valid ctrlBits bits are errorOK, $useOriginalFileName, and $gmt. errorOK suppresses any system-dependent error message that might otherwise occur. If $useOriginalFileName is set, no logical name lookup or application of searchpaths is done; fileName is used as specified. If $gmt is set, $createDate, $createTime, $modifyDate, and $modifyTime are returned in GMT format instead of local time format, if available.