[PATCH] man/man2/setns.2: clarify type of nsfs fd required

[PATCH] man/man2/setns.2: clarify type of nsfs fd required

[Alyssa Ross]

I was surprised to discover than an O_PATH file descriptor was
insufficient.  Since the mode of nsfs files is always 0444, tell
callers to always a file descriptor opened for reading.

Signed-off-by: Alyssa Ross <hi@alyssa.is>
---
 man/man2/setns.2 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/man/man2/setns.2 b/man/man2/setns.2
index ea6a9c054..ed4937280 100644
--- a/man/man2/setns.2
+++ b/man/man2/setns.2
@@ -23,7 +23,7 @@ The
 .I fd
 argument is one of the following:
 .IP \[bu] 3
-a file descriptor referring to one of the magic links in a
+a file descriptor opened for reading one of the magic links in a
 .IR /proc/ pid /ns/
 directory (or a bind mount to such a link);
 .IP \[bu]
@@ -265,6 +265,12 @@ is set to indicate the error.
 .I fd
 is not a valid file descriptor.
 .TP
+.B EBADF
+.I fd
+is an
+.B O_PATH
+file descriptor.
+.TP
 .B EINVAL
 .I fd
 refers to a namespace whose type does not match that specified in

base-commit: 46950a0845de91c422efe6c639091ace42cb92f8
-- 
2.51.0

Re: [PATCH] man/man2/setns.2: clarify type of nsfs fd required

[Alejandro Colomar]

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

Hi Alyssa,

On Sat, Dec 13, 2025 at 06:58:53PM +0100, Alyssa Ross wrote:
> I was surprised to discover than an O_PATH file descriptor was
> insufficient.

How did you discover it?  Could you please link to relevant information
(or kernel sources)?

> Since the mode of nsfs files is always 0444, tell
> callers to always a file descriptor opened for reading.

Missing 'use'?

> 
> Signed-off-by: Alyssa Ross <hi@alyssa.is>


Have a lovely night!
Alex

> ---
>  man/man2/setns.2 | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man2/setns.2 b/man/man2/setns.2
> index ea6a9c054..ed4937280 100644
> --- a/man/man2/setns.2
> +++ b/man/man2/setns.2
> @@ -23,7 +23,7 @@ The
>  .I fd
>  argument is one of the following:
>  .IP \[bu] 3
> -a file descriptor referring to one of the magic links in a
> +a file descriptor opened for reading one of the magic links in a
>  .IR /proc/ pid /ns/
>  directory (or a bind mount to such a link);
>  .IP \[bu]
> @@ -265,6 +265,12 @@ is set to indicate the error.
>  .I fd
>  is not a valid file descriptor.
>  .TP
> +.B EBADF
> +.I fd
> +is an
> +.B O_PATH
> +file descriptor.
> +.TP
>  .B EINVAL
>  .I fd
>  refers to a namespace whose type does not match that specified in
> 
> base-commit: 46950a0845de91c422efe6c639091ace42cb92f8
> -- 
> 2.51.0
> 

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

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

Re: [PATCH] man/man2/setns.2: clarify type of nsfs fd required

[Alyssa Ross]

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

Alejandro Colomar <alx@kernel.org> writes:

> Hi Alyssa,
>
> On Sat, Dec 13, 2025 at 06:58:53PM +0100, Alyssa Ross wrote:
>> I was surprised to discover than an O_PATH file descriptor was
>> insufficient.
>
> How did you discover it?  Could you please link to relevant information
> (or kernel sources)?

By trying it!

Presumably it's the fd_empty() check at the beginning of the syscall
implementation in nsproxy.c.

>> Since the mode of nsfs files is always 0444, tell
>> callers to always a file descriptor opened for reading.
>
> Missing 'use'?

Yes.  Feel free to add it.

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

Re: [PATCH] man/man2/setns.2: clarify type of nsfs fd required

[Alejandro Colomar]

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

Hi Alyssa, Christian, Al,

On Sat, Dec 13, 2025 at 07:59:04PM +0100, Alyssa Ross wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > Hi Alyssa,
> >
> > On Sat, Dec 13, 2025 at 06:58:53PM +0100, Alyssa Ross wrote:
> >> I was surprised to discover than an O_PATH file descriptor was
> >> insufficient.
> >
> > How did you discover it?  Could you please link to relevant information
> > (or kernel sources)?
> 
> By trying it!
> 
> Presumably it's the fd_empty() check at the beginning of the syscall
> implementation in nsproxy.c.

Hmm, thanks!  I don't see any documentation about this, neither in the
kernel Documentation/, nor in the commit messages that introduced this
code.  Christian, Al, would you mind checking if this is intended?  If
so, it would be useful to document why O_PATH is not accepted.  Is it
a security problem?

> >> Since the mode of nsfs files is always 0444, tell
> >> callers to always a file descriptor opened for reading.
> >
> > Missing 'use'?
> 
> Yes.  Feel free to add it.

Thanks!


Cheers,
Alex

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

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