Technical Reference: Base Operating System and Extensions , Volume 2

utimes or utime Subroutine

Purpose

Sets file-access and modification times.

Syntax

#include <sys/time.h>

int utimes ( Path, Times) char *Path; struct timeval Times[2];

#include <utime.h>

int utime ( Path, Times) const char *Path; const struct utimbuf *Times;

The utimes subroutine sets the access and modification times of the file pointed to by the Path parameter to the value of the Times parameter. This subroutine allows time specifications accurate to the second.

The utime subroutine also sets file access and modification times. Each time is contained in a single integer and is accurate only to the nearest second. If successful, the utime subroutine marks the time of the last file-status change (st_ctime) to be updated.

Parameters

Path

Points to the file.

Times

Specifies the date and time of last access and of last modification. For the utimes subroutine, this is an array of timeval structures, as defined in the sys/time.h 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 00:00:00 Greenwich Mean Time (GMT), 1 January 1970, rounded to the nearest second.

For the utime subroutine, this parameter is a pointer to a utimbuf structure, as defined in the utime.h 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 00:00:00 Greenwich Mean Time (GMT), 1 January 1970.

If the Times parameter has a null value, the access and modification times of the file are set to the current time. If the file is remote, the current time at the remote node, rather than the local node, is used. To use the call this way, the effective user ID of the process must be the same as the owner of the file or must have root authority, or the process must have write permission to the file.

If the Times parameter does not have a null value, the access and modification times are set to the values contained in the designated structure, regardless of whether those times are the same as the current time. Only the owner of the file or a user with root authority can use the call this way.

Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned, the errno global variable is set to indicate the error, and the file times are not changed.

Error Codes

The utimes or utime subroutine fails if one of the following is true:

EPERM	The Times parameter is not null and the calling process neither owns the file nor has root user authority.
EACCES	The Times parameter is null, effective user ID is neither the owner of the file nor has root authority, or write access is denied.
EROFS	The file system that contains the file is mounted read-only.

The utimes or utime subroutine can be unsuccessful for other reasons. For a list of additional errors, see "Base Operating System Error Codes For Services That Require Path-Name Resolution."

The utimes or utime subroutine can be unsuccessful for other reasons. For a list of additional errors, see Appendix A, "Base Operating System Error Codes For Services That Require Path-Name Resolution."

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Microsecond time stamps are not implemented, even though the utimes subroutine provides a way to specify them.

Related Information

The stat (statx, stat, lstat, fstatx, fstat, fullstat, ffullstat, stat64, lstat64, or fstat64 Subroutine) subroutine.

Files, Directories, and File Systems for Programmers in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.