Library /sys$common/syshlp/helplib.hlb  —  CRTL  stat
    Accesses information about the specified file.

    Format

      #include  <stat.h>

      int stat  (const char *file_spec, struct stat *buffer);
                (ISO POSIX-1)

      int stat  (const char *file_spec, struct stat *buffer, . . . );
                (DEC C Extension)

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
    stat function that is equivalent to the behavior before OpenVMS
    Version 7.0.

    Compiling with the _USE_STD_STAT feature-test macro defined
    enables a variant of the stat function that uses an X/Open
    standard-compliant definition of the stat structure. The _USE_
    STD_STAT feature-test macro is mutually exclusive with the _DECC_
    V4_SOURCE and _VMS_V6_SOURCE macros.

2  –  Arguments

 file_spec

    A valid OpenVMS or UNIX style file specification (no wildcards).
    Read, write, or execute permission of the named file is not
    required, but you must be able to reach all directories listed
    in the file specification leading to the file.

 buffer

    A pointer to a structure of type stat. For convenience, a typedef
    stat_t is defined as struct stat in the <stat.h> header file.

    This argument receives information about the particular file. The
    members of the structure pointed to by buffer are described in
    the Description section.

  . . .

    An optional default file-name string.

    This is the only optional RMS keyword that can be specified for
    the stat function. See the description of the creat function for
    the full list of optional RMS keywords and their values.

3  –  Description

    When the _USE_STD_STAT feature-test macro is not enabled, the
    legacy stat structure is used. When _USE_STD_STAT is enabled, the
    X/Open standard-compliant stat structure is used.

    Legacy stat Structure

    With the _USE_STD_STAT feature-test macro defined to DISABLE, the
    following legacy stat structure is used:

    Member       Type        Definition

    st_dev       dev_t       Pointer to the 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
    defined in the <stat.h> header file. The st_mode bits are
    described as follows:

    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

    The stat function does not work on remote network files.

    If the file is a record file, the st_size field includes
    carriage-control information. Consequently, the st_size value
    will not correspond to the number of characters that can be read
    from the file.

    Also be aware that for st_size to report a correct value, you
    need to flush both the C RTL and RMS buffers.

    Standard-Compliant stat Structure

    With OpenVMS Version 8.2, the _USE_STD_STAT feature-test macro
    and standard-compliant stat structure are introduced in support
    of UNIX compatibility.

    With _USE_STD_STAT defined to ENABLE, you get the following
    behavior:

    o  Old struct stat definitions

       Old definitions of struct stat are obsolete. You must
       recompile your applications to access the new features.
       Existing applications will continue to access the old
       definitions and functions unless they are recompiled to use
       the new features.

    o  Function variants

       Calls to stat, fstat, lstat, and ftw accept pointers to
       structures of the new type. Calls to these functions are
       mapped to the new library entries __std_stat, __std_fstat,
       __std_lstat, and __std_ftw,  respectively.

    o  Compatibilities with other feature macros

       _DECC_V4_SOURCE source-code compatibility is not supported.
       You must not enable _DECC_V4_SOURCE and _USE_STD_STAT at the
       same time.

       _VMS_V6_SOURCE binary compatibility is not supported. You must
       not enable _VMS_V6_SOURCE and _USE_STD_STAT at the same time.
       As a result, only UTC (rather than local-time) is supported
       for the time_t fields.

    o  Type changes

       The following type changes are in effect:

       -  32-bit gid type gid_t is used. _DECC_SHORT_GID_T is
          unsupported.

       -  _LARGEFILE offsets are used. off_t is forced to 64 bits.

       -  Type ino_t, representing the file number, is an unsigned
          int quadword (64 bits). Previously, it was an unsigned
          short.

       -  Type dev_t, representing the device id, is an unsigned int
          quadword (64 bits). Previously, it was a 32-bit character
          pointer. The new type is standard because it is arithmetic.

       -  Types blksize_t and blkcnt_t are added and defined as
          unsigned int quadwords (64 bits).

    o  Structure member Changes

       -  Two members are added to struct stat:

          blksize_t   st_blksize;
          blkcnt_t    st_blocks;

          According to the X/Open standard, st_blksize is the
          filesystem-specific preferred I/O blocksize for this file.
          On OpenVMS systems, st_blksize is set to the device buffer
          size multiplied by the disk cluster size. st_blocks is set
          to the allocated size of the file, in blocks. The blocksize
          used to calculate st_blocks is not necessarily the same as
          st_blksize and, in most cases, will not be the same.

       -  In struct stat, member st_ino is of type ino_t. In previous
          C RTL versions, it was of type ino_t [3] (array of 3 ino_
          t). Since ino_t has changed from a word to a quadword,
          the size of this member has increased by one word. The
          principal significance of this change is that it makes st_
          ino a scalar, which is how most open source applications
          define it.

       -  The new definition of ino_t also affects applications
          that include the <dirent.h> header file. In struct dirent,
          member d_ino changes in the same way as the st_ino member
          of struct stat in <stat.h>.

       -  Several macros that are not part of any standard were
          introduced in <stat.h> to facilitate access to the
          constituent parts of ino_t values:

             S_INO_NUM(ino), S_INO_SEQ(ino), and S_INO_RVN(ino)
             return the FILES-11 file number, sequence number, and
             relative volume number of ino, respectively, as unsigned
             shorts.

             S_INO_RVN_RVN(ino) returns the byte of the RVN field
             containing the relative volume number;

             S_INO_RVN_NMX(ino) returns the byte of the RVN field
             containing the file number extension.

          Although individual components can be broken out like this,
          they are not part of the X/Open standard and should not be
          relied on in portable applications.

    o  Semantic changes

       Values of type dev_t are now unique for each device across
       clusters. An algorithm based on device name and allocation
       class or SCSSYSTEMID (for single-pathed devices) calculates
       the device id value having these characteristics, an X/Open
       standard requirement. Typically, the combination of file
       number and device id uniquely identifies a file in a cluster.

       This change affects stat structure members st_dev and st_rdev.
       For compatibility with previous releases, st_rdev is set to
       either 0 or st_dev.

                     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 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 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 success.
    -1                 Indicates an error other than a privilege
                       violation; errno is set to indicate the error.
    -2                 Indicates a privilege violation.
Close Help