Skip to contentSkip to conversation

Replacing "master-slave" terminology for pseudoterminals

RFC PATCH In review Michael Kerrisk (man-pages) 3 participants 10 messages Jul 29, 2020 – Aug 4, 2020 1 message not in the archive

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 Replacing "master-slave" terminology for pseudoterminals

As per some discussion on libc-alpha [1], many of us are interested in finding a replacement for the problemantic master-slave terminology used in the description of pseudoterminals.

Elliot Hughes (enh@) suggested a replacement based on an idea from an analogous change in the golang libraries, and I've taken a shot at implementing that idea in a branch [2] of man-pages. The affected pages are:

 man2/ioctl_tty.2    | 23 +++++++++++--------
 man2/poll.2         |  3 ++-
 man3/getpt.3        |  2 +-
 man3/grantpt.3      | 17 +++++++-------
 man3/openpty.3      | 35 ++++++++++++++++------------
 man3/posix_openpt.3 | 10 ++++----
 man3/ptsname.3      | 10 ++++----
 man3/ttyname.3      |  2 +-
 man3/unlockpt.3     | 11 +++++----
 man4/pts.4          | 26 ++++++++++++---------
 man7/pty.7          | 65 +++++++++++++++++++++++++++-------------------------
 11 files changed, 112 insertions(+), 92 deletions(-)

Eventually, I think we should take this discussion also to the mailing list, and also see if we can raise this within the POSIX committee. But let's see if we can fist off find some terminology that seems agreeable.

I've added the full patch below. I am myself still reflecting on the change. At times, the language feels a little clunky, but overall I don't hate the result. I welcome comments from all, and especially I'd be interested in feedback from Elliot and from Zack, who was planning to work on this issue in the glibc documentation.

Thanks,

Michael

[1] https://sourceware.org/pipermail/libc-alpha/2020-July/115792.html
[2] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=pty_lang_fixup

commit 05af4e7c070e4fa6fa810954264d5650b85d162e

Author: Michael Kerrisk <[email protected]>
Date:   Tue Jul 28 22:12:08 2020 +0200

ioctl_tty.2, poll.2, getpt.3, grantpt.3, openpty.3, posix_openpt.3, ptsname.3, ttyname.3, unlockpt.3, pts.4, pty.7: Eliminate problematic "master-slave" terminology

The "master-slave" terminology used in describing pseudoterminals is problematic, and not even very technically descriptive. Rewrite various manual pages to eliminate that language. The following replacement terms are used:

slave ==> "terminal device"
(or "terminal end of the pseudoterminal device pair")

master ==> "pseudoterminal device"
(or "pseudoterminal end of the pseudoterminal device pair")

pseudoterminal (device) ==> "pseudoterminal device pair"

Another notable wording change is the use of phrasings such as "the corresponding terminal device", when emphasizing the linkage between the pseudoterminal and terminal ends of a pseudoterminal device pair.

The terminology originates in golang (which made a similar terminology change in 2019), and was suggested for Linux man-pages by Elliot Hughes.

man2/ioctl_tty.2 +13 -10
index 88ec0269a..7f504928e 100644
@@ -220,7 +220,8 @@ Redirect output that would have gone to
 or
 .I /dev/tty0
 to the given terminal.
-If that was a pseudoterminal master, send it to the slave.
+If that was the pseudoterminal end of a pseudoterminal device pair,
+send it to the corresponding terminal device.
 In Linux before version 2.6.10,
 anybody can do this as long as the output was not redirected yet;
 since version 2.6.10, only a process with the
@@ -283,7 +284,7 @@ Set the foreground process group ID of this terminal.
 Get the session ID of the given terminal.
 This fails with the error
 .B ENOTTY
-if the terminal is not a master pseudoterminal
+if the terminal is not the pseudoterminal end of a pseudoterminal device pair
 and not our controlling terminal.
 Strange.
 .SS Exclusive mode
@@ -322,14 +323,15 @@ Set the line discipline of the terminal.
 Enable (when
 .RI * argp
 is nonzero) or disable packet mode.
-Can be applied to the master side of a pseudoterminal only (and will return
+Can be applied only to the pseudoterminal end of a pseudoterminal device pair
+(and will return
 .B ENOTTY
 otherwise).
 In packet mode, each subsequent
 .BR read (2)
 will return a packet that either contains a single nonzero control byte,
 or has a single byte containing zero (\(aq\e0\(aq) followed by data
-written on the slave side of the pseudoterminal.
+written on the terminal end of the pseudoterminal device pair.
 If the first byte is not
 .B TIOCPKT_DATA
 (0), it is an OR of one
@@ -346,7 +348,7 @@ TIOCPKT_NOSTOP      The start and stop characters are not \fB^S\fP/\fB^Q\fP.
 .IP
 While packet mode is in use, the presence
 of control status information to be read
-from the master side may be detected by a
+from the pseudoterminal end of the device pair may be detected by a
 .BR select (2)
 for exceptional conditions or a
 .BR poll (2)
@@ -371,13 +373,14 @@ Set (if
 .IR *argp
 is nonzero) or remove (if
 .IR *argp
-is zero) the lock on the pseudoterminal slave device.
+is zero) the lock on the terminal end of a pseudoterminal device pair.
 (See also
 .BR unlockpt (3).)
 .TP
 .BI "TIOCGPTLCK	int *" argp
 (since Linux 3.8)
-Place the current lock state of the pseudoterminal slave device
+Place the current lock state of the terminal end of
+a pseudoterminal device pair
 in the location pointed to by
 .IR argp .
 .TP
@@ -386,14 +389,14 @@ in the location pointed to by
 (since Linux 4.13)
 Given a file descriptor in
 .I fd
-that refers to a pseudoterminal master,
+that refers to the pseudoterminal end of a pseudoterminal device pair,
 open (with the given
 .BR open (2)-style
 .IR flags )
 and return a new file descriptor that refers to the peer
-pseudoterminal slave device.
+terminal device.
 This operation can be performed
-regardless of whether the pathname of the slave device
+regardless of whether the pathname of the terminal device
 is accessible through the calling process's mount namespace.
 .IP
 Security-conscious programs interacting with namespaces may wish to use this
man2/poll.2 +2 -1
index 940c51da5..b4428e9f6 100644
@@ -172,7 +172,8 @@ Possibilities include:
 There is out-of-band data on a TCP socket (see
 .BR tcp (7)).
 .IP \(bu
-A pseudoterminal master in packet mode has seen a state change on the slave
+A pseudoterminal device in packet mode has seen a state change on
+the corresponding terminal device
 (see
 .BR ioctl_tty (2)).
 .IP \(bu
man3/getpt.3 +1 -1
index 89c3813a8..65904596d 100644
@@ -6,7 +6,7 @@
 .\"
 .TH GETPT 3 2020-02-09 "GNU" "Linux Programmer's Manual"
 .SH NAME
-getpt \- open a new pseudoterminal master
+getpt \- open a new pseudoterminal device
 .SH SYNOPSIS
 .nf
 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
man3/grantpt.3 +9 -8
index 34c59a52b..c09d50685 100644
@@ -4,7 +4,7 @@
 .\"
 .TH GRANTPT 3 2017-09-15 "GNU" "Linux Programmer's Manual"
 .SH NAME
-grantpt \- grant access to the slave pseudoterminal
+grantpt \- grant access to the terminal device corresponding to a pseudoterminal
 .SH SYNOPSIS
 .B #include <stdlib.h>
 .PP
@@ -30,13 +30,14 @@ Glibc 2.23 and earlier:
 .SH DESCRIPTION
 The
 .BR grantpt ()
-function changes the mode and owner of the slave pseudoterminal device
-corresponding to the master pseudoterminal referred to by the file descriptor
+function changes the mode and owner of the terminal device
+corresponding to the pseudoterminal device referred to by the file descriptor
 .IR fd .
-The user ID of the slave is set to the real UID of the calling process.
+The user ID of the terminal device
+is set to the real UID of the calling process.
 The group ID is set to an unspecified value (e.g.,
 .IR tty ).
-The mode of the slave is set to 0620 (crw\-\-w\-\-\-\-).
+The mode of the terminal device is set to 0620 (crw\-\-w\-\-\-\-).
 .PP
 The behavior of
 .BR grantpt ()
@@ -53,7 +54,7 @@ appropriately.
 .SH ERRORS
 .TP
 .B EACCES
-The corresponding slave pseudoterminal could not be accessed.
+The corresponding terminal device could not be accessed.
 .TP
 .B EBADF
 The
@@ -63,7 +64,7 @@ argument is not a valid open file descriptor.
 .B EINVAL
 The
 .I fd
-argument is valid but not associated with a master pseudoterminal.
+argument is valid but not associated with a pseudoterminal device.
 .SH VERSIONS
 .BR grantpt ()
 is provided in glibc since version 2.1.
@@ -90,7 +91,7 @@ Many systems implement this function via a set-user-ID helper binary
 called "pt_chown".
 On Linux systems with a devpts filesystem (present since Linux 2.2),
 the kernel normally sets the correct ownership and permissions
-for the pseudoterminal slave when the master is opened
+for the corresponding terminal device when the pseudoterminal device is opened
 .RB ( posix_openpt (3)),
 so that nothing must be done by
 .BR grantpt ().
man3/openpty.3 +20 -15
index 9d3dcc236..8580dc9a4 100644
@@ -38,11 +38,11 @@ openpty, login_tty, forkpty \- terminal utility functions
 .nf
 .B #include <pty.h>
 .PP
-.BI "int openpty(int *" amaster ", int *" aslave ", char *" name ,
+.BI "int openpty(int *" fd_pty ", int *" fd_tty ", char *" name ,
 .BI "            const struct termios *" termp ,
 .BI "            const struct winsize *" winp );
 .PP
-.BI "pid_t forkpty(int *" amaster ", char *" name ,
+.BI "pid_t forkpty(int *" fd_pty ", char *" name ,
 .BI "              const struct termios *" termp ,
 .BI "              const struct winsize *" winp );
 
@@ -55,23 +55,26 @@ Link with \fI\-lutil\fP.
 .SH DESCRIPTION
 The
 .BR openpty ()
-function finds an available pseudoterminal and returns file descriptors
-for the master and slave in
-.I amaster
+function finds an available pseudoterminal device pair
+and returns file descriptors
+for the pseudoterminal device and the corresponding terminal device in
+.I fd_pty
 and
-.IR aslave .
+.IR fd_tty .
 If
 .I name
-is not NULL, the filename of the slave is returned in
+is not NULL, the filename of the corresponding terminal device is returned in
 .IR name .
 If
 .I termp
-is not NULL, the terminal parameters of the slave will be set to the
+is not NULL, the terminal parameters of the corresponding terminal device
+will be set to the
 values in
 .IR termp .
 If
 .I winp
-is not NULL, the window size of the slave will be set to the values in
+is not NULL, the window size of the corresponding terminal device
+will be set to the values in
 .IR winp .
 .PP
 The
@@ -79,7 +82,8 @@ The
 function prepares for a login on the terminal
 referred to by the file descriptor
 .I fd
-(which may be a real terminal device, or the slave of a pseudoterminal as
+(which may be a real terminal device,
+or the terminal end of a pseudoterminal device pair as
 returned by
 .BR openpty ())
 by creating a new session, making
@@ -99,19 +103,20 @@ and
 .BR login_tty ()
 to create a new process operating in a pseudoterminal.
 A file descriptor referring to
-master side of the pseudoterminal is returned in
-.IR amaster .
+the pseudoterminal end of the pseudoterminal device pair
+is returned in
+.IR fd_pty .
 If
 .I name
 is not NULL, the buffer it points to is used to return the
-filename of the slave.
+filename of the corresponding terminal device.
 The
 .I termp
 and
 .I winp
 arguments, if not NULL,
-will determine the terminal attributes and window size of the slave
-side of the pseudoterminal.
+will determine the terminal attributes and window size of the terminal end
+of the pseudoterminal device pair.
 .SH RETURN VALUE
 If a call to
 .BR openpty (),
man3/posix_openpt.3 +6 -4
index 6feaae03d..a932cc9f0 100644
@@ -45,7 +45,7 @@ _XOPEN_SOURCE\ >=\ 600
 .SH DESCRIPTION
 The
 .BR posix_openpt ()
-function opens an unused pseudoterminal master device, returning a
+function opens an unused pseudoterminal device, returning a
 file descriptor that can be used to refer to that device.
 .PP
 The
@@ -109,10 +109,12 @@ posix_openpt(int flags)
 .PP
 Calling
 .BR posix_openpt ()
-creates a pathname for the corresponding pseudoterminal slave device.
-The pathname of the slave device can be obtained using
+creates a pathname for the terminal device that corresponds
+to the pseudoterminal.
+The pathname of the terminal device can be obtained using
 .BR ptsname (3).
-The slave device pathname exists only as long as the master device is open.
+The terminal device pathname exists only as long as
+the pseudoterminal device is open.
 .SH SEE ALSO
 .BR open (2),
 .BR getpt (3),
man3/ptsname.3 +5 -5
index 5ae25c5e4..eb3d16cac 100644
@@ -6,7 +6,7 @@
 .\"
 .TH PTSNAME 3 2020-06-09 "" "Linux Programmer's Manual"
 .SH NAME
-ptsname, ptsname_r \- get the name of the slave pseudoterminal
+ptsname, ptsname_r \- get the name of the terminal corresponding to a pseudoterminal
 .SH SYNOPSIS
 .B #include <stdlib.h>
 .PP
@@ -37,15 +37,15 @@ Glibc 2.23 and earlier:
 .SH DESCRIPTION
 The
 .BR ptsname ()
-function returns the name of the slave pseudoterminal device
-corresponding to the master referred to by the file descriptor
+function returns the name of the terminal device
+corresponding to the pseudoterminal device referred to by the file descriptor
 .IR fd .
 .PP
 The
 .BR ptsname_r ()
 function is the reentrant equivalent of
 .BR ptsname ().
-It returns the name of the slave pseudoterminal device as a
+It returns the name of the terminal device as a
 null-terminated string in the buffer pointed to by
 .IR buf .
 The
@@ -79,7 +79,7 @@ glibc 2.25 and earlier.)
 .TP
 .B ENOTTY
 .I fd
-does not refer to a pseudoterminal master device.
+does not refer to a pseudoterminal device.
 .TP
 .B ERANGE
 .RB ( ptsname_r ()
man3/ttyname.3 +1 -1
index 93932610b..cd9831522 100644
@@ -67,7 +67,7 @@ Bad file descriptor.
 .\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23
 .B ENODEV
 .I fd
-refers to a slave pseudoterminal device
+refers to the terminal end of a pseudoterminal device pair
 but the corresponding pathname could not be found (see NOTES).
 .TP
 .B ENOTTY
man3/unlockpt.3 +6 -5
index 26333ef6d..c3d67f4a2 100644
@@ -4,7 +4,7 @@
 .\"
 .TH UNLOCKPT 3 2017-07-13 "" "Linux Programmer's Manual"
 .SH NAME
-unlockpt \- unlock a pseudoterminal master/slave pair
+unlockpt \- unlock a pseudoterminal device pair
 .SH SYNOPSIS
 .B #define _XOPEN_SOURCE
 .br
@@ -32,12 +32,13 @@ Glibc 2.23 and earlier:
 .SH DESCRIPTION
 The
 .BR unlockpt ()
-function unlocks the slave pseudoterminal device
-corresponding to the master pseudoterminal referred to by the file descriptor
+function unlocks the terminal device
+corresponding to the pseudoterminal device referred to by the file descriptor
 .IR fd .
 .PP
 .BR unlockpt ()
-should be called before opening the slave side of a pseudoterminal.
+should be called before opening the terminal end of
+a pseudoterminal device pair.
 .SH RETURN VALUE
 When successful,
 .BR unlockpt ()
@@ -55,7 +56,7 @@ argument is not a file descriptor open for writing.
 .B EINVAL
 The
 .I fd
-argument is not associated with a master pseudoterminal.
+argument is not associated with a pseudoterminal device.
 .SH VERSIONS
 .BR unlockpt ()
 is provided in glibc since version 2.1.
man4/pts.4 +15 -11
index 0b0682433..8897c924a 100644
@@ -7,50 +7,54 @@
 .\"
 .TH PTS 4 2016-03-15 "Linux" "Linux Programmer's Manual"
 .SH NAME
-ptmx, pts \- pseudoterminal master and slave
+ptmx, pts \- pseudoterminal devices
 .SH DESCRIPTION
 The file
 .I /dev/ptmx
 (the pseudoterminal multiplexor device)
 is a character file with major number 5 and
 minor number 2, usually with mode 0666 and ownership root:root.
-It is used to create a pseudoterminal master and slave pair.
+It is used to create a pseudoterminal device pair.
 .PP
 When a process opens
 .IR /dev/ptmx ,
 it gets a file
-descriptor for a pseudoterminal master
-and a pseudoterminal slave device is created in the
+descriptor for a new pseudoterminal device
+and a corresponding terminal device is created in the
 .I /dev/pts
 directory.
 Each file descriptor obtained by opening
 .IR /dev/ptmx
-is an independent pseudoterminal master with its own associated slave,
+is an independent pseudoterminal device with its own associated terminal device,
 whose path can
 be found by passing the file descriptor to
 .BR ptsname (3).
 .PP
-Before opening the pseudoterminal slave, you must pass the master's file
+Before opening the corresponding terminal device,
+you must pass the pseudoterminal device's file
 descriptor to
 .BR grantpt (3)
 and
 .BR unlockpt (3).
 .PP
-Once both the pseudoterminal master and slave are open, the slave provides
+Once both the pseudoterminal device and the terminal device are open,
+the terminal device provides
 processes with an interface that is identical to that of a real terminal.
 .PP
-Data written to the slave is presented on the master file descriptor as input.
-Data written to the master is presented to the slave as input.
+Data written to the terminal device is presented on
+the pseudoterminal device as input.
+Data written to the pseudoterminal device is presented
+to the terminal device as input.
 .PP
 In practice, pseudoterminals are used for implementing terminal emulators
 such as
 .BR xterm (1),
-in which data read from the pseudoterminal master is interpreted by the
+in which data read from the pseudoterminal device is interpreted by the
 application in the same way
 a real terminal would interpret the data, and for implementing remote-login
 programs such as
 .BR sshd (8),
-in which data read from the pseudoterminal master is sent across the network
+in which data read from the pseudoterminal device is sent across the network
 to a client program that is connected to a terminal or terminal emulator.
 .PP
 Pseudoterminals can also be used to send input to programs that normally
man7/pty.7 +34 -31

119 lines not on this page · raw message

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#1 lore raw
Quoted 2 lines

Eventually, I think we should take this discussion also to the mailing list,

That should have read: "the linux-kernel@ mailing list".

#2 lore raw
In reply to Michael Kerrisk (man-pages)
Quoted 27 lines · Michael Kerrisk (man-pages)

As per some discussion on libc-alpha [1], many of us are interested in finding a replacement for the problemantic master-slave terminology used in the description of pseudoterminals.

Elliot Hughes (enh@) suggested a replacement based on an idea from an analogous change in the golang libraries, and I've taken a shot at implementing that idea in a branch [2] of man-pages. The affected pages are:

 man2/ioctl_tty.2    | 23 +++++++++++--------
 man2/poll.2         |  3 ++-
 man3/getpt.3        |  2 +-
 man3/grantpt.3      | 17 +++++++-------
 man3/openpty.3      | 35 ++++++++++++++++------------
 man3/posix_openpt.3 | 10 ++++----
 man3/ptsname.3      | 10 ++++----
 man3/ttyname.3      |  2 +-
 man3/unlockpt.3     | 11 +++++----
 man4/pts.4          | 26 ++++++++++++---------
 man7/pty.7          | 65 +++++++++++++++++++++++++++-------------------------
 11 files changed, 112 insertions(+), 92 deletions(-)

Eventually, I think we should take this discussion also to the mailing list, and also see if we can raise this within the POSIX committee. But let's see if we can fist off find some terminology that seems agreeable.

Quoted 5 lines

I've added the full patch below. I am myself still reflecting on the change. At times, the language feels a little clunky, but overall I don't hate the result. I welcome comments from all, and especially I'd be interested in feedback from Elliot and from Zack, who was planning to work on this issue in the glibc documentation.

Overall I agree with Elliott that the changes are positive and make the pages clearer. In some case I find the verbosity slightly longer than I would want for reading in English. Since I have an EE background I also find multiplexer more natural, but I got lost down the "agent noun from a verb" rabbit hole and I agree with either position.

Signature · 2 lines
Cheers,
Carlos.
#3 lore raw

Hello Carlos,

Thanks for looking at the patch.

Quoted 34 lines · Carlos O'Donell
Quoted 27 lines · Michael Kerrisk (man-pages)

As per some discussion on libc-alpha [1], many of us are interested in finding a replacement for the problemantic master-slave terminology used in the description of pseudoterminals.

Elliot Hughes (enh@) suggested a replacement based on an idea from an analogous change in the golang libraries, and I've taken a shot at implementing that idea in a branch [2] of man-pages. The affected pages are:

 man2/ioctl_tty.2    | 23 +++++++++++--------
 man2/poll.2         |  3 ++-
 man3/getpt.3        |  2 +-
 man3/grantpt.3      | 17 +++++++-------
 man3/openpty.3      | 35 ++++++++++++++++------------
 man3/posix_openpt.3 | 10 ++++----
 man3/ptsname.3      | 10 ++++----
 man3/ttyname.3      |  2 +-
 man3/unlockpt.3     | 11 +++++----
 man4/pts.4          | 26 ++++++++++++---------
 man7/pty.7          | 65 +++++++++++++++++++++++++++-------------------------
 11 files changed, 112 insertions(+), 92 deletions(-)

Eventually, I think we should take this discussion also to the mailing list, and also see if we can raise this within the POSIX committee. But let's see if we can fist off find some terminology that seems agreeable.

Quoted 5 lines

I've added the full patch below. I am myself still reflecting on the change. At times, the language feels a little clunky, but overall I don't hate the result. I welcome comments from all, and especially I'd be interested in feedback from Elliot and from Zack, who was planning to work on this issue in the glibc documentation.

Quoted 3 lines

Overall I agree with Elliott that the changes are positive and make the pages clearer. In some case I find the verbosity slightly longer than I would want for reading in English.

I know what you mean. One reason for that verbosity is the need to clearly distinguish "pseudoterminal device/end" from "pseudoterminal device pair". It's hard to avoid being wordy there.

Quoted 3 lines

Since I have an EE background I also
find multiplexer more natural, but I got lost down the "agent noun from a verb" rabbit hole and I agree with either position.

I was unsure of which to use. It seems both are used, but some quick checking just now shows that "multiplexer" is the rather more widespread spelling, so I've changed it.

Thanks,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#4 lore raw
Quoted 3 lines · Michael Kerrisk (man-pages)

I know what you mean. One reason for that verbosity is the need to clearly distinguish "pseudoterminal device/end" from "pseudoterminal device pair". It's hard to avoid being wordy there.

The perfect is the enemy of the good. My feeling is that as others write this text in emails or discussions, we'll eventually all settle on some other short form we find agreeable and then later we can adjust the man pages to use that. Until then taking the lead to change this language is the correct way forward.

Signature · 2 lines
Cheers,
Carlos.
#5 lore raw
Quoted 10 lines · Carlos O'Donell
Quoted 3 lines · Michael Kerrisk (man-pages)

I know what you mean. One reason for that verbosity is the need to clearly distinguish "pseudoterminal device/end" from "pseudoterminal device pair". It's hard to avoid being wordy there.

The perfect is the enemy of the good. My feeling is that as others write this text in emails or discussions, we'll eventually all settle on some other short form we find agreeable and then later we can adjust the man pages to use that.

based on my own brief experience, i'm expecting that _code_ will settle on pty and tty. but if you're reading the man pages to understand the concepts -- which are inherently quite confusing -- i think spelling things out in longhand might remain useful in that context.

Quoted 2 lines

Until then taking the lead to change this
language is the correct way forward.

yeah, definitely.

i'd prefer for michael to go first -- since the bionic documentation is basically just a link to man7.org, and even without that he's the canonical source -- but i'm happy to go first and submit my change first if it helps us make progress :-)

Quoted 4 lines

--
Cheers,
Carlos.

#6 lore raw

Hi Elliot,

Quoted 21 lines · enh
Quoted 10 lines · Carlos O'Donell
Quoted 3 lines · Michael Kerrisk (man-pages)

I know what you mean. One reason for that verbosity is the need to clearly distinguish "pseudoterminal device/end" from "pseudoterminal device pair". It's hard to avoid being wordy there.

The perfect is the enemy of the good. My feeling is that as others write this text in emails or discussions, we'll eventually all settle on some other short form we find agreeable and then later we can adjust the man pages to use that.

based on my own brief experience, i'm expecting that _code_ will settle on pty and tty. but if you're reading the man pages to understand the concepts -- which are inherently quite confusing -- i think spelling things out in longhand might remain useful in that context.

Quoted 2 lines

Until then taking the lead to change this
language is the correct way forward.

Quoted 6 lines

yeah, definitely.

i'd prefer for michael to go first -- since the bionic documentation is basically just a link to man7.org, and even without that he's the canonical source -- but i'm happy to go first and submit my change first if it helps us make progress :-)

I'd prefer to take this a little slowly. I don't plan to merge the changes just yet. I'm interested to get a bit more feedback first, including from Zack. (I'm guessing Zack is on holiday or so, which is why we've not heard from him.) Also, if we have rough consensus on this change, I would like to raise it with the POSIX folk; it would of course be great if there was a corresponding change in the standard, so that we all (all UNIX) have a common set of reference terms.

Cheers,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#7 lore raw
Quoted 32 lines · Michael Kerrisk (man-pages)

Hi Elliot,

Quoted 21 lines · enh
Quoted 10 lines · Carlos O'Donell
Quoted 3 lines · Michael Kerrisk (man-pages)

I know what you mean. One reason for that verbosity is the need to clearly distinguish "pseudoterminal device/end" from "pseudoterminal device pair". It's hard to avoid being wordy there.

The perfect is the enemy of the good. My feeling is that as others write this text in emails or discussions, we'll eventually all settle on some other short form we find agreeable and then later we can adjust the man pages to use that.

based on my own brief experience, i'm expecting that _code_ will settle on pty and tty. but if you're reading the man pages to understand the concepts -- which are inherently quite confusing -- i think spelling things out in longhand might remain useful in that context.

Quoted 2 lines

Until then taking the lead to change this
language is the correct way forward.

Quoted 6 lines

yeah, definitely.

i'd prefer for michael to go first -- since the bionic documentation is basically just a link to man7.org, and even without that he's the canonical source -- but i'm happy to go first and submit my change first if it helps us make progress :-)

Quoted 8 lines

I'd prefer to take this a little slowly. I don't plan to merge the changes just yet. I'm interested to get a bit more feedback first, including from Zack. (I'm guessing Zack is on holiday or so, which is why we've not heard from him.) Also, if we have rough consensus on this change, I would like to raise it with the POSIX folk; it would of course be great if there was a corresponding change in the standard, so that we all (all UNIX) have a common set of reference terms.

the good news is that it came up at this week's austin group meeting...

the bad news is that (afaik) none of us were there.

i had been planning to suggest we try to join next week anyway, to avoid having this stall again.

Quoted 9 lines

Cheers,

Michael

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

#8 lore raw
Quoted 43 lines · enh
Quoted 32 lines · Michael Kerrisk (man-pages)

Hi Elliot,

Quoted 21 lines · enh
Quoted 10 lines · Carlos O'Donell
Quoted 3 lines · Michael Kerrisk (man-pages)

I know what you mean. One reason for that verbosity is the need to clearly distinguish "pseudoterminal device/end" from "pseudoterminal device pair". It's hard to avoid being wordy there.

The perfect is the enemy of the good. My feeling is that as others write this text in emails or discussions, we'll eventually all settle on some other short form we find agreeable and then later we can adjust the man pages to use that.

based on my own brief experience, i'm expecting that _code_ will settle on pty and tty. but if you're reading the man pages to understand the concepts -- which are inherently quite confusing -- i think spelling things out in longhand might remain useful in that context.

Quoted 2 lines

Until then taking the lead to change this
language is the correct way forward.

Quoted 6 lines

yeah, definitely.

i'd prefer for michael to go first -- since the bionic documentation is basically just a link to man7.org, and even without that he's the canonical source -- but i'm happy to go first and submit my change first if it helps us make progress :-)

Quoted 8 lines

I'd prefer to take this a little slowly. I don't plan to merge the changes just yet. I'm interested to get a bit more feedback first, including from Zack. (I'm guessing Zack is on holiday or so, which is why we've not heard from him.) Also, if we have rough consensus on this change, I would like to raise it with the POSIX folk; it would of course be great if there was a corresponding change in the standard, so that we all (all UNIX) have a common set of reference terms.

Quoted 1 line

the good news is that it came up at this week's austin group meeting...

Yes, I (also) noticed in the Austin group minutes.

Quoted 4 lines

the bad news is that (afaik) none of us were there.

i had been planning to suggest we try to join next week anyway, to avoid having this stall again.

I suggest that we lay the groundwork with an email. I've started crafting a mail to the POSIX folk that will CC all of the parties to the discussion we have already been having, and pointing at the current proposal. I'll send it out tomorrow morning.

One complication in trying to have this discussion on mailing lists is that the Austin list can only be posted to by subscribers :-(.) If you want to participate in the discussion, it may be best to join the Austin Group mailing list (which essentially means joining the Austin Group), if you are not already a member. I think you can find the steps to do so here:

https://www.opengroup.org/austin/lists.html

If you don't do this, your mails to the [email protected] list will be rejected.

Cheers,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

A message that is not in the archive (sent off-list or not yet received): CAJgzZopP=O1cZ2M=3h6Q-X08+eVMPQE_zOCnsEjN=hUTHOkYwQ@mail.gmail.com

#10 lore raw

Hello Elliot,

Thanks for looking at the patch.

Quoted 7 lines · enh

yeah, the old terminology was so non-obvious that reading through this, every change seemed like an improvement in clarity.

my only suggestion would be to consistently use tty_fd and pty_fd in the function signatures rather than just fd. (the presence or absence of 'p' in the function name is a clue, i hadn't picked up on that until i tried rewriting code to use pty/tty rather than master/slave.)

Yes, I've made that change now also.

Quoted 2 lines

(aside: i was surprised by multiplexor rather than multiplexer, but grep says man7.org has 2 multiplexors to 1 multiplexer, so lgtm.)

Carlos also commented on this. I've changed it (and also in other manual pages where "multiplexor" appeared)

Cheers,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/