Advanced Programming in the UNIX® Environment

ptg10805159

126 Files and Directories Chapter 4

4.20 futimens,utimensat,andutimes Functions

Several functions areavailable to change the access time and the modification time of a

file. Thefutimensandutimensatfunctions provide nanosecond granularity for

specifying timestamps, using thetimespecstructure(the same structureused by the

statfamily of functions; see Section 4.2).

#include <sys/stat.h>

int futimens(intfd,const struct timespectimes[2]);

int utimensat(intfd,const char *path,const struct timespectimes[2],

int flag);

Both return: 0 if OK,−1 on error

In both functions, the first element of thetimesarray argument contains the access

time, and the second element contains the modification time. The two time values are

calendar times, which count seconds since the Epoch, as described in Section 1.10.

Partial seconds areexpressed in nanoseconds.

Timestamps can be specified in one of four ways:

1. Thetimesargument is a null pointer.Inthis case, both timestamps areset to the
   current time.


2. Thetimesargument points to an array of twotimespecstructures. If either
   tv_nsecfield has the special valueUTIME_NOW,the corresponding timestamp
   is set to the current time. The correspondingtv_secfield is ignored.


3. Thetimesargument points to an array of twotimespecstructures. If either
   tv_nsecfield has the special value UTIME_OMIT,then the corresponding
   timestamp is unchanged. The correspondingtv_secfield is ignored.


4. Thetimesargument points to an array of twotimespecstructures and the
   tv_nsecfield contains a value other thanUTIME_NOWorUTIME_OMIT.Inthis
   case, the corresponding timestamp is set to the value specified by the
   correspondingtv_secandtv_nsecfields.

The privileges required to execute these functions depend on the value of thetimes

argument.

•Iftimesis a null pointer or if eithertv_nsecfield is set toUTIME_NOW,either

the effective user ID of the process must equal the owner ID of the file, the

process must have write permission for the file, or the process must be a

superuser process.

•Iftimesis a non-null pointer and eithertv_nsecfield has a value other than

UTIME_NOWorUTIME_OMIT,the effective user ID of the process must equal the

owner ID of the file, or the process must be a superuser process. Merely having

write permission for the file is not adequate.