[PATCH] man/man2/link.2: Document new AT_EMPTY_PATH behavior

[PATCH] man/man2/link.2: Document new AT_EMPTY_PATH behavior

[Runxi Yu]

From: Runxi Yu <runxiyu@umich.edu>

Signed-off-by: Runxi Yu <runxiyu@umich.edu>
---
I'm not on the list, so please place my address in the SMTP envelope
recipient.

 man/man2/link.2 | 32 +++++++++++++++++++++++++++-----
 1 file changed, 27 insertions(+), 5 deletions(-)

diff --git a/man/man2/link.2 b/man/man2/link.2
index effed3f74..a888da919 100644
--- a/man/man2/link.2
+++ b/man/man2/link.2
@@ -115,9 +115,30 @@ created with
 and without
 .B O_EXCL
 are an exception).
-The caller must have the
+.\" commit 42bd2af5950456d46fdaa91c3a8fb02e680f19f5
+Since Linux 6.10,
+no privilege is required to use this flag if the credentials under which
+.I olddirfd
+was opened match the caller's current credentials
+(as is normally the case when the caller opened
+.I olddirfd
+itself and has not since altered its credentials).
+Otherwise
+(for example, when
+.I olddirfd
+was received from another process,
+or the caller's credentials have changed since
+.I olddirfd
+was opened),
+the caller must have the
 .B CAP_DAC_READ_SEARCH
-capability in order to use this flag.
+capability in the user namespace of the credentials under which
+.I olddirfd
+was opened.
+Before Linux 6.10,
+the
+.B CAP_DAC_READ_SEARCH
+capability was required in all cases.
 This flag is Linux-specific;
 define
 .B _GNU_SOURCE
@@ -281,9 +302,10 @@ An invalid flag value was specified in
 .B AT_EMPTY_PATH
 was specified in
 .IR flags ,
-but the caller did not have the
-.B CAP_DAC_READ_SEARCH
-capability.
+but the caller lacked the privilege required to create the link;
+see the description of
+.B AT_EMPTY_PATH
+above.
 .TP
 .B ENOENT
 An attempt was made to link to the
-- 
2.55.0

Re: [PATCH] man/man2/link.2: Document new AT_EMPTY_PATH behavior

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2876 bytes --]

[CC += the people involved in the linux.git patch]

Hi Runxi,

On 2026-07-16T09:05:36+0000, Runxi Yu wrote:
> From: Runxi Yu <runxiyu@umich.edu>
> 
> Signed-off-by: Runxi Yu <runxiyu@umich.edu>
> ---
> I'm not on the list, so please place my address in the SMTP envelope
> recipient.

Ack.

>  man/man2/link.2 | 32 +++++++++++++++++++++++++++-----
>  1 file changed, 27 insertions(+), 5 deletions(-)
> 
> diff --git a/man/man2/link.2 b/man/man2/link.2
> index effed3f74..a888da919 100644
> --- a/man/man2/link.2
> +++ b/man/man2/link.2
> @@ -115,9 +115,30 @@ created with
>  and without
>  .B O_EXCL
>  are an exception).
> -The caller must have the
> +.\" commit 42bd2af5950456d46fdaa91c3a8fb02e680f19f5
> +Since Linux 6.10,
> +no privilege is required to use this flag if the credentials under which
> +.I olddirfd
> +was opened match the caller's current credentials

The commit message says this is not enough.  The credentials must not
have changed since olddirfd was opened.  Restoring credentials wouldn't
work.

Here's what the commit message says:

    Note that the credential equality check is done by using pointer
    equality, which means that it's not enough that you have effectively the
    same user - they have to be literally identical, since our credentials
    are using copy-on-write semantics.

> +(as is normally the case when the caller opened
> +.I olddirfd
> +itself and has not since altered its credentials).

This is not the normal case where it happens, but actually the only case
that is allowed.

> +Otherwise
> +(for example, when
> +.I olddirfd
> +was received from another process,
> +or the caller's credentials have changed since
> +.I olddirfd
> +was opened),
> +the caller must have the
>  .B CAP_DAC_READ_SEARCH
> -capability in order to use this flag.
> +capability in the user namespace of the credentials under which

I feel this reads a bit weird.  Would it be better to remove
'of the credentials' in the line above?  Or should it stay?

> +.I olddirfd
> +was opened.
> +Before Linux 6.10,
> +the
> +.B CAP_DAC_READ_SEARCH
> +capability was required in all cases.

I think we can move this to HISTORY.

>  This flag is Linux-specific;
>  define
>  .B _GNU_SOURCE
> @@ -281,9 +302,10 @@ An invalid flag value was specified in
>  .B AT_EMPTY_PATH
>  was specified in
>  .IR flags ,
> -but the caller did not have the
> -.B CAP_DAC_READ_SEARCH
> -capability.
> +but the caller lacked the privilege required to create the link;
> +see the description of
> +.B AT_EMPTY_PATH
> +above.

Let's remove the last three lines.  This is of course implied when
talking about AT_EMPTY_PATH.


Have a lovely day!
Alex

>  .TP
>  .B ENOENT
>  An attempt was made to link to the
> -- 
> 2.55.0
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]