utime(), utime64() — Set file access and modification times

Standards

Standards / Extensions C or C++ Dependencies
POSIX.1
XPG4
XPG4.2
Single UNIX Specification, Version 3
 both  

Format

utime:
#define _POSIX_SOURCE
#include <utime.h>

int utime(const char *pathname, const struct utimbuf *newtimes);
utime64:
#define _POSIX_SOURCE
#define _LARGE_TIME_API 
#include <utime.h>

int utime64(const char *pathname, const struct utimbuf64 *newtimes);

Compile requirement: Use of the utime64() function requires the long long data type. For more information on how to make the long long data type available, see z/OS XL C/C++ Language Reference.

General description

Function utime() sets the access and modification times of pathname to the values in the utimbuf structure. If newtimes is a NULL pointer, the access and modification times are set to the current time.

Normally, the effective user ID (UID) of the calling process must match the owner UID of the file, or the calling process must have appropriate privileges. However, if newtimes is a NULL pointer, the effective UID of the calling process must match the owner UID of the file, or the calling process must have write permission to the file or appropriate privileges.

The contents of a utimbuf structure are:
time_t actime
The new access time (The time_t type gives the number of seconds since the epoch.)
time_t modtime
The new modification time

The utime64() function behaves exactly like utime() except utime64() uses struct utimbuf64 instead of struct utimbuf to support times beyond 03:14:07 UTC on January 19, 2038.

The contents of a utimbuf64 structure are as follows:
time64_t actime
The new access time (The time64_t type gives the number of seconds since the epoch.)
time64_t modtime
The new modification time

Returned value

If successful, utime() returns 0 and updates the access and modification times of the file to those specified.

If unsuccessful, utime() returns -1, does not update file times, and sets errno to one of the following values:
Error Code
Description
EACCES
The process does not have search permission on some component of the pathname prefix; or all of the following are true:
  • newtimes is NULL.
  • The effective user ID of the process does not match the file's owner.
  • The process does not have write permission on the file.
  • The process does not have appropriate privileges.
ELOOP
A loop exists in symbolic links. This error is issued if more than POSIX_SYMLOOP symbolic links (defined in the limits.h header file) are detected in the resolution of pathname.
ENAMETOOLONG
pathname is longer than PATH_MAX characters, or some component of pathname is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of the pathname string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined using pathconf().
ENOENT
There is no file named pathname, or the pathname argument is an empty string.
ENOTDIR
Some component of the pathname prefix is not a directory.
EPERM
newtimes is not NULL, 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
pathname is on a read-only file system.

Example

CELEBU07 
/* CELEBU07 */
#define _POSIX_SOURCE
#include <fcntl.h>
#include <stdio.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <time.h>
#include <unistd.h>
#include <utime.h>

main() {
  int fd;
  char fn[]="utime.file";
  struct utimbuf ubuf;

  if ((fd = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    close(fd);
    puts("before utime()");
    system("ls -l utime.file");
    ubuf.modtime = 0;
    time(&ubuf.actime);
    if (utime(fn, &ubuf) != 0)
      perror("utime() error");
    else {
      puts("after utime()");
      system("ls -l utime.file");
    }
    unlink(fn);
  }
}
Output 
before utime()
--w-------   1 WELLIE   SYS1           0 Apr 19 15:23 utime.file
after utime()
--w-------   1 WELLIE   SYS1           0 Dec 31  1969 utime.file

Related information