HELPLIB.HLB  —  CRTL  utimes
    Sets file access and modification times.

    Format

      #include  <time.h>

      int utimes  (const char *path, const struct timeval times[2]);

1  –  Arguments

 path

    A pointer to a file.

 times

    an array of timeval structures. The first array member represents
    the date and time of last access, and the second member
    represents the date and time of last modification. The times
    in the timeval structure are measured in seconds and microseconds
    since the Epoch, although rounding toward the nearest second may
    occur.

2  –  Description

    The utimes function sets the access and modification times of the
    file pointed to by the path argument to the value of the times
    argument. The utimes function allows time specifications accurate
    to the microsecond.

    If the times argument is a NULL pointer, the access and
    modification times of the file are set to the current time. The
    effective user ID of the process must be the same as the owner
    of the file, or must have write access to the file or appropriate
    privileges to use this call in this manner.

    Upon completion, utimes marks the time of the last file status
    change, st_ctime, for update.

                     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 0, 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.

3  –  Return Values

    0                  Successful execution.
    -1                 Indicates an error. The file times do not
                       change and the function sets errno to one of
                       the following values:

                       The utimes function will fail if:

                       o  EACCES - Search permission is denied by
                          a component of the path prefix; or the
                          times argument is a NULL pointer and the
                          effective user ID of the process does
                          not match the owner of the file and write
                          access is denied.

                       o  ELOOP - Too many symbolic links were
                          encountered in resolving path.

                       o  ENAMETOOLONG - The length of the path
                          argument exceeds PATH_MAX, a pathname
                          component is longer than NAME_MAX, or a
                          pathname resolution of a symbolic link
                          produced an intermediate result whose
                          length exceeds PATH_MAX.

                       o  ENOENT - A component of path does not
                          name an existing file, or path is an empty
                          string.

                       o  ENOTDIR - A component of the path prefix is
                          not a directory.

                       o  EPERM -The times argument is not a NULL
                          pointer and the calling process's effective
                          user ID has write-access to the file but
                          does not match the owner of the file and
                          the calling process does not have the
                          appropriate privileges.

                       o  EROFS - The file system containing the file
                          is read-only.
Close Help