diff mbox series

[v2,5/5] manual: Document futimens and utimensat

Message ID 20250106163257.705106-6-arjun@redhat.com (mailing list archive)
State New
Headers
Series manual: Document several *at file system interface functions |

Checks

Context Check Description
redhat-pt-bot/TryBot-apply_patch success Patch applied to master at the time it was sent
redhat-pt-bot/TryBot-32bit success Build for i686
linaro-tcwg-bot/tcwg_glibc_build--master-arm success Build passed
linaro-tcwg-bot/tcwg_glibc_check--master-arm success Test passed
linaro-tcwg-bot/tcwg_glibc_build--master-aarch64 success Build passed
linaro-tcwg-bot/tcwg_glibc_check--master-aarch64 success Test passed

Commit Message

Arjun Shankar Jan. 6, 2025, 4:26 p.m. UTC 
  ---
 manual/filesys.texi | 69 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 68 insertions(+), 1 deletion(-)

Comments

Florian Weimer Jan. 8, 2025, 8:26 a.m. UTC | #1 
* Arjun Shankar:

> ---
>  manual/filesys.texi | 69 ++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 68 insertions(+), 1 deletion(-)
>
> diff --git a/manual/filesys.texi b/manual/filesys.texi
> index ba2f13ef96..a5a5e1a1b4 100644
> --- a/manual/filesys.texi
> +++ b/manual/filesys.texi
> @@ -3273,6 +3273,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

“@code{const struct timespec *} type“

> +precision; see @ref{Time Types}.

I think this should be: precision.  @xref{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.

These error codes are not guaranteed, especially not for time64
translation, where we simply crash.

> +@item EINVAL
> +At least of the fields in the @code{tsp} array passed has an invalid value.
> +
> +@end table
> +@end deftypefun

These errors can happen with futimes, too, no?  Not sure if it is
necessary to document those separately.

There's also EOVERFLOW (coming from __utimensat64_helper).

> +@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}.

Maybe mention that if @var{filename} is null, the function behaves
similar to futimens?

> +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}.

Does this reflect the recent change to permit null file name arguments?

> +
> +@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.

The empty string does not refer to an existing file, either.  Should
this mention AT_EMPTY_PATH?

> +@item ENOTDIR
> +The file descriptor @var{filedes} is not associated with a directory.

And is not AT_FDCWD?

Thanks,
Florian
diff mbox series

Patch

diff --git a/manual/filesys.texi b/manual/filesys.texi
index ba2f13ef96..a5a5e1a1b4 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -3273,6 +3273,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
 
@@ -3889,5 +3957,4 @@  The @code{mkdtemp} function comes from OpenBSD.
 @c renameat2
 @c scandirat
 @c symlinkat
-@c utimensat
 @c mknodat