utime() — 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

#define _POSIX_SOURCE
#include <utime.h>

int utime(const char *pathname, const struct utimbuf *newtimes);

General description

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

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