utime(2)                            CLIX                            utime(2)



  NAME

    utime - Sets file access and modification times

  LIBRARY

    Standard C Library (libc.a)

  SYNOPSIS

    #include <sys/types.h>

    #include <utime.h>

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

  PARAMETERS

    path    Points to the pathname of the file.

    times   Points to a utimbuf structure, defined in the <utime.h> header
            file as follows:

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

            The first structure 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 utimbuf structure are measured in
            seconds since the Epoch, 00:00:00 Greenwich Mean Time (GMT),
            January 1, 1970.

  DESCRIPTION

    The utime() function sets file access and modification times.

    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 be the same
    as the owner of the file, or have write permission to use the call in this
    manner.

    If times is not the NULL value, the access and modification times are set
    to the values contained in the designated structure, regardless of whether
    those times correlate with the current time.  Only the owner of the file
    or the superuser can use the call this way.

  EXAMPLES



  2/94 - Intergraph Corporation                                              1

  utime(2)                            CLIX                            utime(2)



    1.  To set the accessed and modified times of a file to the current time:

        if (utime("filename", (struct utimbuf *)0) == -1)
                perror("utime failed");


    2.  To set the accessed and modified times to some specific values:

        struct utimbuf ut;
        ut.actime = desired_actime;
        ut.modtime = desired_modtime;
        if (utime("filename", &ut) == -1)
                perror("utime failed");


  RETURN VALUES

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

  ERRORS

    The utime() function fails if one or more of the following are true:

    [ENOENT]
           The named file does not exist.

    [EPERM]
           The times parameter is not the NULL value and the calling process's
           effective user ID does not match the owner of the file and the
           calling process does not have the appropriate privileges.

    [EACCES]
           Search permission is denied by a component of the path prefix.
           This error also occurs if the times parameter is NULL and effective
           user ID of the caller is not the owner of the file and write access
           is denied.

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

    [ENAMETOOLONG]
           The length of path exceeds PATH_MAX or a pathname component is
           longer than NAME_MAX while _POSIX_NO_TRUNC is in effect.

    [EFAULT]
           The path or times parameter is an invalid address.

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



  2                                              Intergraph Corporation - 2/94

  utime(2)                            CLIX                            utime(2)



    [EINTR]
           A signal was caught during the utime() function.

    [ENOLINK]
           The path parameter points to a remote machine and the link to that
           machine is no longer active.

    [EMULTIHOP]
           Components of path require hopping to multiple remote machines.

  RELATED INFORMATION

    Functions:  stat(2)

    Files: utime.h







































  2/94 - Intergraph Corporation                                              3