utime(S)                       6 January 1993                       utime(S)


 Name

    utime - set file access and modification times

 Syntax


    cc  . . .  -lc


    #include <sys/types.h>
    #include <utime.h>

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


 Description

    The utime function sets the access and modification times of the file
    named by the path argument.

    If times is NULL, the access and modification times of the file are set
    to the current time.  The effective user ID of the process must match the
    owner of the file, or the process must have write permission to the file
    or have super user privileges to use utime in this manner.

    If times is not NULL, 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 a process with effective
    user ID equal to the user ID of the file or a process with super user
    privileges may use utime this way.

    The utimbuf structure is defined by the header <utime.h>.  The times in
    the structure utimbuf are measured in seconds since the ``Epoch'',
    00:00:00 Greenwich Mean Time (GMT), January 1, 1970.

       struct  utimbuf  {
               time_t actime;         /* access time */
               time_t modtime;        /* modification time */
       };

    The utime system call fails if one or more of the following is true:

    [EACCES]       The effective user ID is not super user and not the owner
                   of the file, and times is null and write access is denied,
                   or search permission is denied by a component of the path
                   prefix.

    [EINTR]        A signal was caught during the utime system call.

    [EMULTIHOP]    Components of path require hopping to multiple remote ma-
                   chines.

    [ENAMETOOLONG] The length of the path argument exceeds PATHMAX or a
                   pathname component is longer than NAMEMAX while
                   POSIXNOTRUNC is in effect.

    [ENOENT]       The named file does not exist or the path argument points
                   to an empty string.

    [ENOLINK]      path points to a remote machine, and the link to that ma-
                   chine is no longer active.

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

    [EPERM]        The effective user ID has write access to the file, but is
                   not super user and not the owner of the file, and times is
                   not NULL.

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


 Diagnostics

    Upon successful completion, a value of 0 is returned.  Otherwise, a value
    of -1 is returned, and errno is set to indicate the error, and the file
    times are not affected.

 See also

    stat(S)

 Standards conformance

    utime is conformant with:
    AT&T SVID Issue 2;
    X/Open Portability Guide, Issue 3, 1989;
    Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2);
    IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C
    Language] (ISO/IEC 9945-1);
    and NIST FIPS 151-1.