Advanced Programming in the UNIX® Environment

(lily) #1
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.
Free download pdf