HELPLIB.HLB  —  CRTL  fstat
    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.
Close Help