#### 14.10.9 File Times ¶

Each file has three time stamps 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.

Reading from a file updates its access time attribute, and writing updates its modification time. When a file is created, all three time stamps 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 the attributes of a file (for example, with `chmod`) updates its attribute change time field.

You can also change some of the time stamps 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)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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 to by times.

  The attribute modification time for the file is set to the current time in either case (since changing the time stamps 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 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 time stamp on the file, you must either be the owner of the file, have write permission for 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.

  `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 Time Types.

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, const struct timeval tvp`[2]`)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  This function sets the file access and modification times of the file filename. The new file access time is specified by `tvp[0]`, and the new modification time by `tvp[1]`. Similar to `utime`, if tvp is a null pointer then the access and modification times of the file are set to the current time. This function comes from BSD.

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

Function: `int` lutimes `(const char *filename, const struct timeval tvp`[2]`)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  This function is like `utimes`, except that it does not follow symbolic links. If filename is the name of a symbolic link, `lutimes` sets the file access and modification times of the symbolic link special file itself (as seen by `lstat`; see Symbolic Links) while `utimes` sets the file access and modification times of the file the symbolic link refers to. This function comes from FreeBSD, and is not available on all platforms (if not available, it will fail with `ENOSYS`).

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

Function: `int` futimes `(int fd, const struct timeval tvp`[2]`)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  This function is like `utimes`, except that it takes an open file descriptor as an argument instead of a file name. See Low-Level Input/Output. This function comes from FreeBSD, and is not available on all platforms (if not available, it will fail with `ENOSYS`).

  Like `utimes`, `futimes` returns `0` on success and `-1` on failure. The following `errno` error conditions are defined for `futimes`:

  `EACCES`

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

  `EBADF`

    The filedes argument is not a valid file descriptor.

  `EINVAL`

    At least one of the fields in the `tvp` array passed has an invalid value.

  `EPERM`

    If the times argument is not a null pointer, you must either be the owner of the file or be a privileged user.

  `EROFS`

    The file lives on a read-only file system.

Function: `int` futimens `(int filedes, const struct timespec tsp`[2]`)` ¶

  | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt | See POSIX Safety Concepts.

  This function is like `futimes`, except that it sets the file access and modification timestamps with nanosecond precision. The argument `tsp` is used similarly to `futimes`’ `tvp`, but has a `const struct timespec` type that can express calendar time with nanosecond precision. See Time Types.

Function: `int` utimensat `(int filedes, const char *filename, const struct timespec tsp`[2]`, int flags)` ¶

  | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt | See POSIX Safety Concepts.

  This function is a descriptor-relative version of the `futimens` function above. See Descriptor-Relative Access. The flags argument can contain a combination of the flags `AT_EMPTY_PATH`, and `AT_SYMLINK_NOFOLLOW`. The call:

      futimens (filedes, tsp)

  is equivalent to:

      utimensat (filedes, NULL, tsp, 0)

  Compared to `futimens`, some additional error conditions can occur due to descriptor-relative access. See Descriptor-Relative Access. In addition to this, the following other errors can also occur:

  `EINVAL`

    The filename argument is NULL, filedes is not `AT_FDCWD`, and flags is not `0`.

  `ELOOP`

    There are too many levels of indirection. This can be the result of circular symbolic links to directories.

  `ENAMETOOLONG`

    The resulting path is too long. This error only occurs on systems which have a limit on the file name length.

  `ENOENT`

    The filename argument is an empty string and flags does not contain `AT_EMPTY_PATH`, or filename does not refer to an existing file.

  `ESRCH`

    Search permission was denied for one of the prefix components of the the filename argument.