[PATCH v2 4/5] manual: Document unlinkat

[Florian Weimer]

* Arjun Shankar:

> ---
>  manual/filesys.texi | 35 ++++++++++++++++++++++++++++++++++-
>  1 file changed, 34 insertions(+), 1 deletion(-)
>
> diff --git a/manual/filesys.texi b/manual/filesys.texi
> index 776b98fe7f..ba2f13ef96 100644
> --- a/manual/filesys.texi
> +++ b/manual/filesys.texi
> @@ -1695,6 +1695,40 @@ file system and can't be modified.
>  @end table
>  @end deftypefun
>  
> +@deftypefun int unlinkat (int @var{filedes}, const char *@var{filename}, int @var{flags})
> +@standards{POSIX.1-2008, unistd.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{unlink}
> +function above.  @xref{Descriptor-Relative Access}.  The @var{flags}
> +argument may either be @code{0} or contain the flag @code{AT_REMOVEDIR}:
> +
> +@table @code
> +@item AT_REMOVEDIR
> +This flag causes @code{unlinkat} to perform an @code{rmdir} operation on
> +@code{filename} instead of performing the equivalent of @code{unlink}.
> +@end table
> +
> +Compared to @code{unlink}, the following additional error conditions can
> +occur:
> +
> +@table @code
> +@item EBADF
> +The @var{filedes} argument is not a valid file descriptor.

Usual comment about AT_FDCWD.

> +@item EINVAL
> +The @var{flags} argument is not valid for this function.
> +
> +@item EISDIR
> +@var{filename} is a directory but the @var{AT_REMOVEDIR} was not passed in
> +@code{flags}.

Please do not start a sentence with @var.  Perhapse use “The effective
final path component is a directory”?

> +@item ENOTDIR
> +The descriptor @var{filedes} is not associated with a directory, and
> +@var{filename} is a relative file name.

I think AT_FDCWD is permitted as well.  But also consider the earlier
comment that we should document EBADF/EINVAL/ENOTDIR in the generic
section.

Thanks,
Florian