gtpc2m9cC/C++ Language Support User's Guide

utime-Set File Access and Modification Times

This function sets file access and modification times.

Format

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

pathname
The file whose time stamp will be changed.

newtimes
A pointer to a structure, utimbuf, that specifies the new access and modification times.

This function 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 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 UID of the calling process must match the owner UID of the file, or the calling proess must have write permission to the file or appropriate privileges.

The contents of a utimbuf structure are:

Normal Return

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

Error Return

If unsuccessful, the utime functions returns the value -1, does not update the file times and sets errno to one of the following:

EACCES
The process did not have search permission for some component of the pathname prefix; or all of the following are true:

EBUSY
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
The pathname is longer than PATH_MAX characters, or some component of pathname is longer than NAME_MAX characters. For symbolic links, the length of the path name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined using the pathconf function.

ENOENT
There is no file names pathname, or the pathname argument is an empty string.

ENOTDIR
Some component of the pathname is not a directory.

EPERM
The newtimes specified 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
The pathname specified is on a read-only file system.

Programming Considerations

None.

Examples

The following example creates a file, utime.file, and then uses the utime function to modify the timestamp of the file.

#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>
 
int main(void) {
  int fd;
  char fn[]="utime.file";
  struct utimbuf ubuf;
 
  if ((fd = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    close(fd);
    ubuf.modtime = 0;
    time(ubuf.actime);
    if (utime(fn, ubuf) != 0
      perror("utime() error");
    unlink(fn);
  }
  return 0;
}

Related Information

See Appendix E, Programming Support for the TPF File System for more information about TPF File System C Functions.