The GNU C Library - File Times

File Times

Each file has three timestamps associated with it: its access time, its modification time, and its attribute modification time. These correspond to the st_atime , st_mtime , and st_ctime members of the stat structure; see File Attributes.

All of these times are represented in calendar time format, as time_t objects. This data type is defined in `time.h'. For more information about representation and manipulation of time values, see Calendar Time.

When an existing file is opened, its attribute change time and modification time fields are updated. Reading from a file updates its access time attribute, and writing updates its modification time.

When a file is created, all three timestamps for that file are set to the current time. In addition, the attribute change time and modification time fields of the directory that contains the new entry are updated.

Adding a new name for a file with the link function updates the attribute change time field of the file being linked, and both the attribute change time and modification time fields of the directory containing the new name. These same fields are affected if a file name is deleted with unlink , remove , or rmdir . Renaming a file with rename affects only the attribute change time and modification time fields of the two parent directories involved, and not the times for the file being renamed.

Changing attributes of a file (for example, with chmod ) updates its attribute change time field.

You can also change some of the timestamps of a file explicitly using the utime function---all except the attribute change time. You need to include the header file `utime.h' to use this facility.

Data Type struct utimbuf

The utimbuf structure is used with the utime function to specify new access and modification times for a file. It contains the following members:

time_t actime

This is the access time for the file.

time_t modtime

This is the modification time for the file.

Function int utime (const char *filename, const struct utimbuf *times)

This function is used to modify the file times associated with the file named filename.

If times is a null pointer, then the access and modification times of the file are set to the current time. Otherwise, they are set to the values from the actime and modtime members (respectively) of the utimbuf structure pointed at by times.

The attribute modification time for the file is set to the current time in either case (since changing the timestamps is itself a modification of the file attributes).

The utime function returns 0 if successful and -1 on failure. In addition to the usual file name syntax errors (see File Name Errors), the following errno error conditions are defined for this function:

EACCES

There is a permission problem in the case where a null pointer was passed as the times argument. In order to update the timestamp on the file, you must either be the owner of the file, have write permission on the file, or be a privileged user.

ENOENT

The file doesn't exist.

EPERM

If the times argument is not a null pointer, you must either be the owner of the file or be a privileged user. This error is used to report the problem.

EROFS

The file lives on a read-only file system.

Each of the three time stamps has a corresponding microsecond part, which extends its resolution. These fields are called st_atime_usec , st_mtime_usec , and st_ctime_usec ; each has a value between 0 and 999,999, which indicates the time in microseconds. They correspond to the tv_usec field of a timeval structure; see High-Resolution Calendar.

The utimes function is like utime , but also lets you specify the fractional part of the file times. The prototype for this function is in the header file `sys/time.h'.

Function int utimes (const char *filename, struct timeval tvp[2])

This function sets the file access and modification times for the file named by filename. The new file access time is specified by tvp[0] , and the new modification time by tvp[1] . This function comes from BSD.

The return values and error conditions are the same as for the utime function.