# utime

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           utime — set file access and modification times
    


## SYNOPSIS



           #include <utime.h>
    
           int utime(const char *_path_ , const struct utimbuf *_times_);
    


## DESCRIPTION



           The _utime_() function shall set the access and modification times
           of the file named by the _path_ argument.
    
           If _times_ is a null pointer, the access and modification times of
           the file shall be set to the current time. The effective user ID
           of the process shall match the owner of the file, or the process
           has write permission to the file or has appropriate privileges, to
           use _utime_() in this manner.
    
           If _times_ is not a null pointer, _times_ shall be interpreted as a
           pointer to a **utimbuf** structure and the access and modification
           times shall be set to the values contained in the designated
           structure. Only a process with the effective user ID equal to the
           user ID of the file or a process with appropriate privileges may
           use _utime_() this way.
    
           The **utimbuf** structure is defined in the _< utime.h>_ header. The
           times in the structure **utimbuf** are measured in seconds since the
           Epoch.
    
           Upon successful completion, the _utime_() function shall mark the
           last file status change timestamp for update; see _< sys/stat.h>_.
    


## RETURN VALUE



           Upon successful completion, 0 shall be returned. Otherwise, -1
           shall be returned and _errno_ shall be set to indicate the error,
           and the file times shall not be affected.
    


## ERRORS



           The _utime_() function shall fail if:
    
           **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, the process does not have write permission for
                  the file, and the process does not have appropriate
                  privileges.
    
           **ELOOP** A loop exists in symbolic links encountered during
                  resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  The length of a component of a pathname is longer than
                  {NAME_MAX}.
    
           **ENOENT** A component of _path_ does not name an existing file or _path_
                  is an empty string.
    
           **ENOTDIR**
                  A component of the path prefix names an existing file that
                  is neither a directory nor a symbolic link to a directory,
                  or the _path_ argument contains at least one non-<slash>
                  character and ends with one or more trailing <slash>
                  characters and the last pathname component names an
                  existing file that is neither a directory nor a symbolic
                  link to a directory.
    
           **EPERM** The _times_ argument is not a null pointer and the effective
                  user ID of the calling process does not match the owner of
                  the file and the calling process does not have appropriate
                  privileges.
    
           **EROFS** The file system containing the file is read-only.
    
           The _utime_() function may fail if:
    
           **ELOOP** More than {SYMLOOP_MAX} symbolic links were encountered
                  during resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  The length of a pathname exceeds {PATH_MAX}, or pathname
                  resolution of a symbolic link produced an intermediate
                  result with a length that exceeds {PATH_MAX}.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           Since the **utimbuf** structure only contains **time_t** variables and is
           not accurate to fractions of a second, applications should use the
           _utimensat_() function instead of the obsolescent _utime_() function.
    


## RATIONALE



           The _actime_ structure member must be present so that an application
           may set it, even though an implementation may ignore it and not
           change the last data access timestamp on the file. If an
           application intends to leave one of the times of a file unchanged
           while changing the other, it should use _stat_() or _fstat_() to
           retrieve the file's _st_atim_ and _st_mtim_ parameters, set _actime_ and
           _modtime_ in the buffer, and change one of them before making the
           _utime_() call.
    


## FUTURE DIRECTIONS



           The _utime_() function may be removed in a future version.
    


* * *