Index for Section 2

Alphabetical listing for U

Bottom of page

utime(2)
NAME
  utime, utimes - Set file access and modification times

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

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

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

  The following definitions of the utime() and utimes() functions do not
  conform to current standards and are supported only for backward
  compatibility.

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

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

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  utime(): XSH4.0, XSH4.2, XSH5.0

  utimes(): XSH4.2, XSH5.0

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  path
      Points to the file.  If the final component of the path parameter names
      a symbolic link, the link will be traversed and pathname resolution
      will continue.

  times
      Points to a utimbuf structure for the utime() function, or to an array
      of timeval structures for the utimes() function.

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

  The utime() function also sets file access and modification times; however,
  each time is contained in a single integer and is accurate only to the
  nearest second.

  For utime(), the times parameter is a pointer to a utimbuf structure,
  defined in the <utime.h> header file. 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, January 1, 1970, Coordinated
  Universal Time (UTC)).

  For utimes(), the times parameter is an array of timeval structures, as
  defined in the <sys/time.h> header file. The first array element represents
  the date and time of last access, and the second element 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.

  If the times parameter is null, the access and modification times of the
  file are set to the current time. If the file is a remote file, the current
  time at the remote node, rather than the local node, is used. 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 superuser privilege in order to use the
  call in this manner.

  If the times parameter is not null, 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 a user with superuser privilege can use the call this way.

  Upon successful completion, the utime() and utimes() functions mark the
  time of the last file status change, st_ctime, for update.

NOTES
  The utime() and utimes() functions are not recommended for operations, such
  as backing up or archiving files, that need to change a file's atime
  (access time) or mtime (modification time) but not change the file's ctime
  (attribute change time). For such operations, use the fcntl() function's
  F_GETTIMES and F_SETTIMES requests. See fcntl(2) for more information.

RETURN VALUES
  Upon successful completion, a value of 0 (zero) is returned. Otherwise, a
  value of -1 is returned, errno is set to indicate the error, and the file
  times will not be affected.

ERRORS
  If the utimes() or utime() function fails, errno may be set to one of the
  following values:

  [EACCES]
      Search permission is denied by a component of the path prefix; or the
      times parameter is null and the effective user ID is neither the owner
      of the file nor has appropriate system privilege, and write access is
      denied.

  [EFAULT]
      [Tru64 UNIX]  The path parameter is an invalid address, or (for
      utimes()) either the path or times parameter is an invalid address.

  [EINVAL]
      [Tru64 UNIX]  The file is not a regular file.

  [ELOOP]
      Too many links were encountered in translating path.

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

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

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

  [EPERM]
      The times parameter is not the null value and the calling process has
      write access to the file but neither owns the file nor has the
      appropriate system privilege.

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

  [ESTALE]
      [Tru64 UNIX]  The process' root or current directory is located in a
      virtual file system that has been unmounted.

  The utimes() function can also fail if additional errors occur.

SEE ALSO
  Functions: fcntl(2), stat(2)

  Standards: standards(5)

Index for Section 2

Alphabetical listing for U

Top of page