From: Arjun Shankar <arjun@redhat.com>
Date: Wed, 4 Jun 2025 11:08:58 +0000 (+0200)
Subject: manual: Document futimens and utimensat
X-Git-Tag: glibc-2.42~159
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=25f1d945766a3a757d9b54eb48fe7c3c48c0f791;p=thirdparty%2Fglibc.git

manual: Document futimens and utimensat

Document futimens and utimensat.  Also document the EINVAL error
condition for futimes.  It is inherited by futimens and utimensat as
well.
Reviewed-by: Florian Weimer <fweimer@redhat.com>
---

diff --git a/manual/filesys.texi b/manual/filesys.texi
index 396d68c329..f21f218042 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -3307,6 +3307,10 @@ permission for the file, or be a privileged user.
 @item EBADF
 The @var{filedes} argument is not a valid file descriptor.
 
+@item EINVAL
+At least one of the fields in the @code{tvp} array passed has an invalid
+value.
+
 @item EPERM
 If the @var{times} argument is not a null pointer, you must either be
 the owner of the file or be a privileged user.
@@ -3316,6 +3320,64 @@ 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{const struct timespec} type that can express calendar time with
+nanosecond precision.  @xref{Time Types}.
+@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}.  The call:
+
+@smallexample
+futimens (@var{filedes}, @var{tsp})
+@end smallexample
+
+is equivalent to:
+
+@smallexample
+utimensat (@var{filedes}, @code{NULL}, @var{tsp}, 0)
+@end smallexample
+
+Compared to @code{futimens}, some additional error conditions can occur due
+to descriptor-relative access.  @xref{Descriptor-Relative Access}.  In
+addition to this, the following other errors can also occur:
+
+@table @code
+@item EINVAL
+The @var{filename} argument is NULL, @var{filedes} is not @code{AT_FDCWD},
+and @var{flags} is not @code{0}.
+
+@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 and @var{flags} does not
+contain @code{AT_EMPTY_PATH}, or @var{filename} does not refer to an
+existing file.
+
+@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
 
@@ -3932,5 +3994,4 @@ The @code{mkdtemp} function comes from OpenBSD.
 @c renameat2
 @c scandirat
 @c symlinkat
-@c utimensat
 @c mknodat