Accesses information about the file specified by the file
descriptor.
Format
#include <stat.h>
int fstat (int file_desc, struct stat *buffer);
1 – Function Variants
Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
test macros defined enables a local-time-based entry point to the
fstat function that is equivalent to the behavior before OpenVMS
Version 7.0.
2 – Arguments
file_desc
A file descriptor.
buffer
A pointer to a structure of type stat_t, which is defined in the
<stat.h> header file. The argument receives information about
that particular file. The members of the structure pointed to by
buffer are:
Member Type Definition
st_dev dev_t Pointer to a physical device name
st_ino[3] ino_t Three words to receive the file ID
st_mode mode_t File "mode" (prot, dir, . . . )
st_nlink nlink_t For UNIX system compatibility only
st_uid uid_t Owner user ID
st_gid gid_t Group member: from st_uid
st_rdev dev_t UNIX system compatibility - always 0
st_size off_t File size, in bytes. For st_size to
report a correct value, you need to
flush both the C RTL and RMS buffers.
st_atime time_t File access time; always the same as
st_mtime
st_mtime time_t Last modification time
st_ctime time_t File creation time
st_fab_rfm char Record format
st_fab_rat char Record attributes
st_fab_fsz char Fixed header size
st_fab_mrs unsigned Record size
The types dev_t, ino_t, off_t, mode_t, nlink_t, uid_t, gid_t, and
time_t, are defined in the <stat.h> header file. However, when
compiling for compatibility (/DEFINE=_DECC_V4_SOURCE), only dev_
t, ino_t, and off_t are defined.
The off_t data type is either a 32-bit or 64-bit integer. The 64-
bit interface allows for file sizes greater than 2 GB, and can be
selected at compile time by defining the _LARGEFILE feature-test
macro as follows:
CC/DEFINE=_LARGEFILE
As of OpenVMS Version 7.0, times are given in seconds since the
Epoch (00:00:00 GMT, January 1, 1970).
The st_mode structure member is the status information mode and
is defined in the <stat.h> header file. The st_mode bits follow:
Bits Constant Definition
0170000 S_IFMT Type of file
0040000 S_IFDIR Directory
0020000 S_IFCHR Character special
0060000 S_IFBLK Block special
0100000 S_IFREG Regular
0030000 S_IFMPC Multiplexed char special
0070000 S_IFMPB Multiplexed block special
0004000 S_ISUID Set user ID on execution
0002000 S_ISGID Set group ID on execution
0001000 S_ISVTX Save swapped text even after use
0000400 S_IREAD Read permission, owner
0000200 S_IWRITE Write permission, owner
0000100 S_IEXEC Execute/search permission, owner
3 – Description
The fstat function does not work on remote network files.
Be aware that for the stat_t structure member st_size to report a
correct value, you need to flush both the C RTL and RMS buffers.
NOTE (Integrity servers, Alpha)
On OpenVMS Alpha and Integrity server systems, the stat,
fstat, utime, and utimes functions have been enhanced to
take advantage of the new file-system support for POSIX
compliant file timestamps.
This support is available only on ODS-5 devices on OpenVMS
Alpha and Integrity servers systems beginning with a version
of OpenVMS Alpha after Version 7.3.
Before this change, the stat and fstat functions were
setting the values of the st_ctime, st_mtime, and st_atime
fields based on the following file attributes:
st_ctime - ATR$C_CREDATE (file creation time)
st_mtime - ATR$C_REVDATE (file revision time)
st_atime - was always set to st_mtime because no support
for file access time was available
Also, for the file-modification time, utime and utimes were
modifying the ATR$C_REVDATE file attribute, and ignoring the
file-access-time argument.
After the change, for a file on an ODS-5 device, the stat
and fstat functions set the values of the st_ctime, st_
mtime, and st_atime fields based on the following new file
attributes:
st_ctime - ATR$C_ATTDATE (last attribute modification
time)
st_mtime - ATR$C_MODDATE (last data modification time)
st_atime - ATR$C_ACCDATE (last access time)
If ATR$C_ACCDATE is zero, as on an ODS-2 device, the stat
and fstat functions set st_atime to st_mtime.
For the file-modification time, the utime and utimes
functions modify both the ATR$C_REVDATE and ATR$C_MODDATE
file attributes. For the file-access time, these functions
modify the ATR$C_ACCDATE file attribute. Setting the ATR$C_
MODDATE and ATR$C_ACCDATE file attributes on an ODS-2 device
has no effect.
For compatibility, the old behavior of stat, fstat, utime,
and utimes remains the default, regardless of the kind of
device.
The new behavior must be explicitly enabled at run time
by defining the DECC$EFS_FILE_TIMESTAMPS logical name to
"ENABLE" before invoking the application. Setting this
logical does not affect the behavior of stat, fstat, utime
and utimes for files on an ODS-2 device.
4 – Return Values
0 Indicates successful completion.
-1 Indicates an error other than a protection
violation.
-2 Indicates a protection violation.