[PATCH 5/5] manual: Document futimens and utimensat

[Arjun Shankar]

---
 manual/filesys.texi | 69 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 68 insertions(+), 1 deletion(-)

diff --git a/manual/filesys.texi b/manual/filesys.texi
index f2b2cea872..34b5dc4fcb 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -3267,6 +3267,74 @@ The file lives on a read-only file system.
 @end table
 @end deftypefun
 
+@deftypefun int futimens (int @var{filedes}, const struct timespec @var{tsp}@t{[2]})
+@standards{POSIX.1-2008, sys/stat.h}
+@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default
+@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+This function is like @code{futimes}, except that it sets the file access
+and modification timestamps with nanosecond precision.  The argument
+@code{tsp} is used similarly to @code{futimes}' @code{tvp}, but has a
+@code{struct timespec} type that can express calendar time with nanosecond
+precision; see @ref{Time Types}.
+
+Compared to @code{futimes}, the following additional error conditions can
+occur:
+
+@table @code
+@item EFAULT
+The @var{tsp} argument points to an invalid address.
+
+@item EINVAL
+At least of the fields in the @code{tsp} array passed has an invalid value.
+
+@end table
+@end deftypefun
+
+@deftypefun int utimensat (int @var{filedes}, const char *@var{filename}, const struct timespec @var{tsp}@t{[2]}, int @var{flags})
+@standards{POSIX.1-2008, sys/stat.h}
+@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default
+@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+This function is a descriptor-relative version of the @code{futimens}
+function above.  @xref{Descriptor-Relative Access}.  The @var{flags}
+argument can contain a combination of the flags @code{AT_EMPTY_PATH},
+and @code{AT_SYMLINK_NOFOLLOW}.
+
+Compared to @code{futimens}, the following additional error conditions can
+occur:
+
+@table @code
+@item EFAULT
+The @var{filedes} argument is @code{AT_FDCWD} and @var{filename} is NULL or
+points to an invalid address.
+
+@item EINVAL
+The @var{flags} argument is not valid for this function.
+
+@item EINVAL
+The @var{filename} argument is NULL, @var{filedes} is not @code{AT_FDCWD},
+and @var{flags} contains @code{AT_SYMLINK_NOFOLLOW}.
+
+@item ELOOP
+There are too many levels of indirection.  This can be the result of
+circular symbolic links to directories.
+
+@item ENAMETOOLONG
+The resulting path is too long.  This error only occurs on systems which
+have a limit on the file name length.
+
+@item ENOENT
+The @var{filename} argument is an empty string or does not refer to an
+existing file.
+
+@item ENOTDIR
+The file descriptor @var{filedes} is not associated with a directory.
+
+@item ESRCH
+Search permission was denied for one of the prefix components of the the
+@var{filename} argument.
+@end table
+@end deftypefun
+
 @node File Size
 @subsection File Size
 
@@ -3883,5 +3951,4 @@ The @code{mkdtemp} function comes from OpenBSD.
 @c renameat2
 @c scandirat
 @c symlinkat
-@c utimensat
 @c mknodat
-- 
2.47.1