ttyname.3: document ENODEV error code

Hi,

Thanks Dmitry. One comment

On 20 Mar 2017 9:51 p.m., "Dmitry V. Levin" <ldv-u2l5PoMzF/[email protected]> wrote:

---
 man3/ttyname.3 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

man3/ttyname.3 +5 -0

index 14c24e7..0be50c6 100644
@@ -71,6 +71,11 @@ File descriptor does not refer to a terminal device.
 .RB ( ttyname_r ())
 .I buflen
 was too small to allow storing the pathname.
+.TP
+.\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23
+.B ENODEV
+File descriptor refers to a slave pseudoterminal device
+but the corresponding pathname could not be found.
 

I think it would be good to explicitly mention that ENODEV is set in case the fd does not refer to a pts device in its namespace. Otherwise users might take this as an indication that this is a more generic error which is not the case.

Hi,

Quoted 24 lines · Christian Brauner

Hi,

Thanks Dmitry. One comment

On 20 Mar 2017 9:51 p.m., "Dmitry V. Levin" <ldv-u2l5PoMzF/[email protected]> wrote:

---
 man3/ttyname.3 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

man3/ttyname.3 +5 -0

index 14c24e7..0be50c6 100644
@@ -71,6 +71,11 @@ File descriptor does not refer to a terminal device.
 .RB ( ttyname_r ())
 .I buflen
 was too small to allow storing the pathname.
+.TP
+.\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23
+.B ENODEV
+File descriptor refers to a slave pseudoterminal device
+but the corresponding pathname could not be found.
 

Quoted 4 lines

I think it would be good to explicitly mention that ENODEV is set in case the fd does not refer to a pts device in its namespace. Otherwise users might take this as an indication that this is a more generic error which is not the case.

In fact, this is a more generic error than a namespace mismatch, although the latter is the most likely reason.

Imagine that the corresponding file inside /dev/pts/ is not available for some reason and the stat call has failed. This situation could be reproduced e.g. by bind-mounting an empty directory to /dev/pts. A subsequent ttyname invocation would end up with ENODEV because the device is literally not available although it's withing the same namespace.

I don't mind if you change the description to mention the namespace case as the most likely, but please do not make it the only case when ENODEV can happen.

Hi Dmitry,

Quoted 41 lines · Dmitry V. Levin

Hi,

Quoted 24 lines · Christian Brauner

Hi,

Thanks Dmitry. One comment

On 20 Mar 2017 9:51 p.m., "Dmitry V. Levin" <ldv-u2l5PoMzF/[email protected]> wrote:

---
 man3/ttyname.3 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

man3/ttyname.3 +5 -0

index 14c24e7..0be50c6 100644
@@ -71,6 +71,11 @@ File descriptor does not refer to a terminal device.
 .RB ( ttyname_r ())
 .I buflen
 was too small to allow storing the pathname.
+.TP
+.\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23
+.B ENODEV
+File descriptor refers to a slave pseudoterminal device
+but the corresponding pathname could not be found.
 

Quoted 4 lines

I think it would be good to explicitly mention that ENODEV is set in case the fd does not refer to a pts device in its namespace. Otherwise users might take this as an indication that this is a more generic error which is not the case.

In fact, this is a more generic error than a namespace mismatch, although the latter is the most likely reason.

Imagine that the corresponding file inside /dev/pts/ is not available for some reason and the stat call has failed. This situation could be reproduced e.g. by bind-mounting an empty directory to /dev/pts. A subsequent ttyname invocation would end up with ENODEV because the device is literally not available although it's withing the same namespace.

Quoted 3 lines

I don't mind if you change the description to mention the namespace case as the most likely, but please do not make it the only case when ENODEV can happen.

I'm open on this point. If someone wants to write a suitable patch, I'll probably take it.

Sorry, for the late reply.

Quoted 44 lines · Michael Kerrisk (man-pages)

Hi Dmitry,

Quoted 41 lines · Dmitry V. Levin

Hi,

Quoted 24 lines · Christian Brauner

Hi,

Thanks Dmitry. One comment

On 20 Mar 2017 9:51 p.m., "Dmitry V. Levin" <ldv-u2l5PoMzF/[email protected]> wrote:

---
 man3/ttyname.3 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

man3/ttyname.3 +5 -0

index 14c24e7..0be50c6 100644
@@ -71,6 +71,11 @@ File descriptor does not refer to a terminal device.
 .RB ( ttyname_r ())
 .I buflen
 was too small to allow storing the pathname.
+.TP
+.\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23
+.B ENODEV
+File descriptor refers to a slave pseudoterminal device
+but the corresponding pathname could not be found.
 

Quoted 4 lines

I think it would be good to explicitly mention that ENODEV is set in case the fd does not refer to a pts device in its namespace. Otherwise users might take this as an indication that this is a more generic error which is not the case.

In fact, this is a more generic error than a namespace mismatch, although the latter is the most likely reason.

Imagine that the corresponding file inside /dev/pts/ is not available for some reason and the stat call has failed. This situation could be reproduced e.g. by bind-mounting an empty directory to /dev/pts. A subsequent ttyname invocation would end up with ENODEV because the device is literally not available although it's withing the same namespace.

Quoted 6 lines

Quoted 3 lines

I don't mind if you change the description to mention the namespace case as the most likely, but please do not make it the only case when ENODEV can happen.

I'm open on this point. If someone wants to write a suitable patch, I'll probably take it.

This point is in my opinion crucial. The over-mounting scenario is still a valid case for most programs that do not actually care about what /dev/pts/<n> is actually used to go on which is a nice side-effect of the patch. The namespace part should be mentioned since ttyname{_r}() explicitly does not return anything when it detects that /proc/self/fd/<n> points to /dev/pts/<n> but /dev/pts/<n> does not exist in the same namespace. This was the original motivation when we wrote the patch. So users that get ENODEV from ttyname{_r}() should be aware that resolving the symlink manually afterwards doesn't give them a /dev/pts/<n> path valid in the current namespace.

I'll put this on my TODO list but if someone is willing to send a patch right away
please do so. :)

Quoted 66 lines · Christian Brauner

Sorry, for the late reply.

Quoted 44 lines · Michael Kerrisk (man-pages)

Hi Dmitry,

Quoted 41 lines · Dmitry V. Levin

Hi,

Quoted 24 lines · Christian Brauner

Hi,

Thanks Dmitry. One comment

On 20 Mar 2017 9:51 p.m., "Dmitry V. Levin" <ldv-u2l5PoMzF/[email protected]> wrote:

---
 man3/ttyname.3 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

man3/ttyname.3 +5 -0

index 14c24e7..0be50c6 100644
@@ -71,6 +71,11 @@ File descriptor does not refer to a terminal device.
 .RB ( ttyname_r ())
 .I buflen
 was too small to allow storing the pathname.
+.TP
+.\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23
+.B ENODEV
+File descriptor refers to a slave pseudoterminal device
+but the corresponding pathname could not be found.
 

Quoted 4 lines

I think it would be good to explicitly mention that ENODEV is set in case the fd does not refer to a pts device in its namespace. Otherwise users might take this as an indication that this is a more generic error which is not the case.

In fact, this is a more generic error than a namespace mismatch, although the latter is the most likely reason.

Imagine that the corresponding file inside /dev/pts/ is not available for some reason and the stat call has failed. This situation could be reproduced e.g. by bind-mounting an empty directory to /dev/pts. A subsequent ttyname invocation would end up with ENODEV because the device is literally not available although it's withing the same namespace.

Quoted 6 lines

Quoted 3 lines

I don't mind if you change the description to mention the namespace case as the most likely, but please do not make it the only case when ENODEV can happen.

I'm open on this point. If someone wants to write a suitable patch, I'll probably take it.

This point is in my opinion crucial. The over-mounting scenario is still a valid case for most programs that do not actually care about what /dev/pts/<n> is actually used to go on which is a nice side-effect of the patch. The namespace part should be mentioned since ttyname{_r}() explicitly does not return anything when it detects that /proc/self/fd/<n> points to /dev/pts/<n> but /dev/pts/<n> does not exist in the same namespace. This was the original motivation when we wrote the patch. So users that get ENODEV from ttyname{_r}() should be aware that resolving the symlink manually afterwards doesn't give them a /dev/pts/<n> path valid in the current namespace.

Quoted 3 lines

I'll put this on my TODO list but if someone is willing to send a patch right away
please do so. :)

Hi Christian,

I think you may be best placed to know what you want to convey here. I'd be happy to receive a patch.

Cheers,

Michael

Signed-off-by Christian Brauner <christian.brauner-GeWIH/[email protected]>

---
 man3/ttyname.3 | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

man3/ttyname.3 +1 -1

index 0be50c62a..f184b4505 100644
@@ -75,7 +75,7 @@ was too small to allow storing the pathname.
 .\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23
 .B ENODEV
 File descriptor refers to a slave pseudoterminal device
-but the corresponding pathname could not be found.
+but the corresponding pathname could not be found (see NOTES).
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
 .BR attributes (7).

@@ -93,6 +93,22 @@ T}	Thread safety	MT-Safe
 .TE
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008, 4.2BSD.

Quoted 26 lines · Christian Brauner

Signed-off-by Christian Brauner <christian.brauner-GeWIH/[email protected]>

---
 man3/ttyname.3 | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

man3/ttyname.3 +5 -1

index 0be50c62a..f184b4505 100644
@@ -75,7 +75,7 @@ was too small to allow storing the pathname.
 .\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23
 .B ENODEV
 File descriptor refers to a slave pseudoterminal device
-but the corresponding pathname could not be found.
+but the corresponding pathname could not be found (see NOTES).
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
 .BR attributes (7).

@@ -93,6 +93,22 @@ T}	Thread safety	MT-Safe
 .TE
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008, 4.2BSD.
+.SH NOTES
+Processes keeping a file descriptor to a
+.BR pts (4)
+device open when switching to

man3/ttyname.3 T} Thread safety MT-Safe · line 105

Quoted 6 lines

man3/ttyname.3 +6 -0

+.BR mount_namespaces (7)
+that use a different
+.IR /dev/ptmx
+instance may still accidently find that a device path of the same name
+for that file descriptor exists. However, this device path refers to a
+different device and thus cannot not be used to modify the device that

s/to modify the device/to access the device/

Signed-off-by Christian Brauner <christian.brauner-GeWIH/[email protected]>

---
 man3/ttyname.3 | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

man3/ttyname.3 +17 -1

index 0be50c62a..f184b4505 100644
@@ -75,7 +75,7 @@ was too small to allow storing the pathname.
 .\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23
 .B ENODEV
 File descriptor refers to a slave pseudoterminal device
-but the corresponding pathname could not be found.
+but the corresponding pathname could not be found (see NOTES).
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
 .BR attributes (7).

@@ -93,6 +93,22 @@ T}	Thread safety	MT-Safe
 .TE
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008, 4.2BSD.
+.SH NOTES
+Processes keeping a file descriptor to a
+.BR pts (4)
+device open when switching to
+.BR mount_namespaces (7)
+that use a different
+.IR /dev/ptmx
+instance may still accidently find that a device path of the same name
+for that file descriptor exists. However, this device path refers to a
+different device and thus cannot not be used to modify the device that
+the file descriptor refers to. Calling
+.BR ttyname (7)
+or
+.BR ttyname_r (7)
+on the file descriptor in such a mount namespace will cause these
+functions to return NULL and set errno to ENODEV.
 .SH SEE ALSO
 .BR tty (1),
 .BR fstat (2),

---
 man3/ttyname.3 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

man3/ttyname.3 +7 -1

index 14c24e7..0be50c6 100644
@@ -71,6 +71,11 @@ File descriptor does not refer to a terminal device.
 .RB ( ttyname_r ())
 .I buflen
 was too small to allow storing the pathname.
+.TP
+.\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23
+.B ENODEV
+File descriptor refers to a slave pseudoterminal device
+but the corresponding pathname could not be found.
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
 .BR attributes (7).

@@ -92,4 +97,5 @@ POSIX.1-2001, POSIX.1-2008, 4.2BSD.
 .BR tty (1),
 .BR fstat (2),
 .BR ctermid (3),
-.BR isatty (3)
+.BR isatty (3),
+.BR pts (4)