utime(2)                                                           utime(2)




 NAME    [Toc]    [Back]
      utime() - set file access and modification times

 SYNOPSIS    [Toc]    [Back]
      #include <utime.h>

      int utime(const char *path, const struct utimbuf *times);

 DESCRIPTION    [Toc]    [Back]
      The utime() system call sets the access and modification times of the
      file to which the path argument refers.

      If times is a NULL pointer, the access and modification times of the
      file are set to the current time.  A process must be the owner of the
      file or have write permission on the file to use utime() in this
      manner.

      If times is not a NULL pointer, times is interpreted as a pointer to a
      utimbuf structure, and the access and modification times are set to
      the values contained in the designated structure.  Only the owner of
      the file or a user with appropriate privileges can use utime() this
      way.

      The following times in the utimbuf structure defined in <utime.h> are
      measured in seconds since 00:00:00 UTC (Coordinated Universal Time),
      January 1, 1970.

           time_t actime;     /* access time */
           time_t modtime;    /* modification time */

 RETURN VALUE    [Toc]    [Back]
      utime() returns the following values:

            0   Successful completion.
           -1   Failure.  errno is set to indicate the error.

 ERRORS    [Toc]    [Back]
      If utime() fails, errno is set to one of the following values.

           [EACCES]       Search permission is denied by a component of the
                          path prefix.

           [EACCES]       The effective user ID is not a user with
                          appropriate privileges, and not the owner of the
                          file, times is a NULL pointer, and write access is
                          denied.

           [EFAULT]       times is not a NULL pointer, and it points outside
                          the process's allocated address space.  The
                          reliable detection of this error is
                          implementation-dependent.



 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 utime(2)                                                           utime(2)




           [EFAULT]       path points outside the process's allocated
                          address space.  The reliable detection of this
                          error is implementation-dependent.

           [EINVAL]       times is not a NULL pointer, and access time or
                          modification time or both are negative.

           [ENAMETOOLONG] The length of the specified path name exceeds
                          PATH_MAX bytes, or the length of a component of
                          the path name exceeds NAME_MAX bytes while
                          _POSIX_NO_TRUNC is in effect.

           [ENOENT]       The named file does not exist.

           [ENOTDIR]      A component of the path prefix is not a directory.

           [EPERM]        The effective user ID is not a user with
                          appropriate privileges.  and not the owner of the
                          file, and times is not a NULL pointer.

           [EROFS]        The file system containing the file is mounted
                          read-only.

 DEPENDENCIES    [Toc]    [Back]
    NFS
      utime() may return [EPERM] when invoked on a remote file owned by a
      superuser, even if the invoking user has write permission on the file.

 SEE ALSO    [Toc]    [Back]
      touch(1), stat(2).

 STANDARDS CONFORMANCE    [Toc]    [Back]
      utime(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1


 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003