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

[Florian Weimer]

* 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