[PATCH] manual: Clarify renameat documentation

[Collin Funk]

Hi Jitka,

Jitka Obselkova <jobselko@redhat.com> writes:

> Improved documentation based on
> https://inbox.sourceware.org/libc-alpha/87v7pb4jvy.fsf@oldenburg.str.redhat.com/
>
> -- 
> Jitka Obselkova
> From 2c3d70dd932ab04eb5397edee0fb554e3f652f7b Mon Sep 17 00:00:00 2001
> From: Jitka Obselkova <jobselko@redhat.com>
> Date: Sat, 14 Jun 2025 11:19:46 +0200
> Subject: [PATCH] manual: Clarify renameat documentation
>
> Clarify the meaning of renameat arguments.
>
> Signed-off-by: Jitka Obselkova <jobselko@redhat.com>
> ---
>  manual/filesys.texi | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/manual/filesys.texi b/manual/filesys.texi
> index f21f218042..46621e8a92 100644
> --- a/manual/filesys.texi
> +++ b/manual/filesys.texi
> @@ -1940,7 +1940,9 @@ file systems.
>  @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{rename}
> -function above.  @xref{Descriptor-Relative Access}.
> +function above.  @xref{Descriptor-Relative Access}.  The @var{oldname} is
> +interpreted relative to @var{oldfiledes} and @var{newname} is interpreted
> +relative to @var{newfiledes}.
>  
>  Compared to @code{rename}, some additional error conditions can occur.
>  @xref{Descriptor-Relative Access}.

This is only true of OLDNAME and NEWNAME are relative paths. Quoting
POSIX [1]:

    The renameat() function shall be equivalent to the rename() function
    except in the case where either old or new specifies a relative
    path. If old is a relative path, the file to be renamed is located
    relative to the directory associated with the file descriptor oldfd
    instead of the current working directory.

I think it is worth mentioning that.

Collin

[1] https://pubs.opengroup.org/onlinepubs/9799919799/functions/renameat.html