102 this manner. Upon completion, \fButimes()\fR will mark the time of the last
 103 file status change, \fBst_ctime\fR, for update.
 104 .sp
 105 .LP
 106 The \fBfutimens()\fR and \fButimensat()\fR functions also set access and
 107 modification times; however, instead of taking \fBstruct timeval\fR, they take
 108 \fBtimespec_t\fR which allows for nanosecond granularity. The \fBfutimens()\fR
 109 function sets the access and modification times on the file descriptor
 110 referenced by \fIfiledes\fR.
 111 .sp
 112 .LP
 113 The \fButimensat()\fR function determines the file to set the access and
 114 modification times in an similar way to \fBfutemsat()\fR. If the argument
 115 \fIpath\fR is an absolute path, then the argument \fIfiledes\fR is ignored;
 116 otherwise, \fIpath\fR is interpreted as a path relative to the directory
 117 specified by \fIfiledes\fR. If \fIfiledes\fR is set to \fBAT_FDCWD\fR, then
 118 \fIpath\fR is resolved relative to the current working directory. The behavior
 119 when encountering symbolic links may be controlled by the value of the
 120 \fIflag\fR argument. If the value of flag is the constant
 121 \fBAT_SYMLINK_NOFOLLOW\fR, then when a symbolic link is encountered while
 122 resoloving a path, it will not be followed. Otherwise, the value of \fIflag\fR
 123 should be \fB0\fR.
 124 .SH RETURN VALUES
 125 .LP
 126 Upon successful completion, \fB0\fR is returned.  Otherwise, \fB\(mi1\fR is
 127 returned, \fBerrno\fR is set to indicate the error, and the file times will not
 128 be affected.
 129 .SH ERRORS
 130 .LP
 131 The \fButimes()\fR, \fBfutimesat()\fR, \fBfutimens()\fR, and \fButimensat()\fR
 132 functions will fail if:
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBEACCES\fR\fR
 137 .ad
 138 .RS 16n
 139 Search permission is denied by a component of the path prefix; or the
 140 \fItimes\fR argument is a null pointer and the effective user \fBID\fR of the
 141 process does not match the owner of the file and write access is denied.
 142 .RE

 102 this manner. Upon completion, \fButimes()\fR will mark the time of the last
 103 file status change, \fBst_ctime\fR, for update.
 104 .sp
 105 .LP
 106 The \fBfutimens()\fR and \fButimensat()\fR functions also set access and
 107 modification times; however, instead of taking \fBstruct timeval\fR, they take
 108 \fBtimespec_t\fR which allows for nanosecond granularity. The \fBfutimens()\fR
 109 function sets the access and modification times on the file descriptor
 110 referenced by \fIfiledes\fR.
 111 .sp
 112 .LP
 113 The \fButimensat()\fR function determines the file to set the access and
 114 modification times in an similar way to \fBfutemsat()\fR. If the argument
 115 \fIpath\fR is an absolute path, then the argument \fIfiledes\fR is ignored;
 116 otherwise, \fIpath\fR is interpreted as a path relative to the directory
 117 specified by \fIfiledes\fR. If \fIfiledes\fR is set to \fBAT_FDCWD\fR, then
 118 \fIpath\fR is resolved relative to the current working directory. The behavior
 119 when encountering symbolic links may be controlled by the value of the
 120 \fIflag\fR argument. If the value of flag is the constant
 121 \fBAT_SYMLINK_NOFOLLOW\fR, then when a symbolic link is encountered while
 122 resolving a path, it will not be followed. Otherwise, the value of \fIflag\fR
 123 should be \fB0\fR.
 124 .SH RETURN VALUES
 125 .LP
 126 Upon successful completion, \fB0\fR is returned.  Otherwise, \fB\(mi1\fR is
 127 returned, \fBerrno\fR is set to indicate the error, and the file times will not
 128 be affected.
 129 .SH ERRORS
 130 .LP
 131 The \fButimes()\fR, \fBfutimesat()\fR, \fBfutimens()\fR, and \fButimensat()\fR
 132 functions will fail if:
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBEACCES\fR\fR
 137 .ad
 138 .RS 16n
 139 Search permission is denied by a component of the path prefix; or the
 140 \fItimes\fR argument is a null pointer and the effective user \fBID\fR of the
 141 process does not match the owner of the file and write access is denied.
 142 .RE