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" terminologypty_lang_fixup

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.

Reported-by: Elliott Hughes <enh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

11 files changed, 112 insertions, 92 deletions

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index 88ec0269ae..7f504928ec 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -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
diff --git a/man2/poll.2 b/man2/poll.2
index 940c51da52..b4428e9f6d 100644
--- a/man2/poll.2
+++ b/man2/poll.2
@@ -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
diff --git a/man3/getpt.3 b/man3/getpt.3
index 89c3813a8b..65904596d9 100644
--- a/man3/getpt.3
+++ b/man3/getpt.3
@@ -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) */"
diff --git a/man3/grantpt.3 b/man3/grantpt.3
index 34c59a52b6..c09d50685a 100644
--- a/man3/grantpt.3
+++ b/man3/grantpt.3
@@ -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 ().
diff --git a/man3/openpty.3 b/man3/openpty.3
index 9d3dcc2366..8580dc9a4b 100644
--- a/man3/openpty.3
+++ b/man3/openpty.3
@@ -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 (),
diff --git a/man3/posix_openpt.3 b/man3/posix_openpt.3
index 6feaae03da..a932cc9f07 100644
--- a/man3/posix_openpt.3
+++ b/man3/posix_openpt.3
@@ -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),
diff --git a/man3/ptsname.3 b/man3/ptsname.3
index 5ae25c5e4b..eb3d16cac8 100644
--- a/man3/ptsname.3
+++ b/man3/ptsname.3
@@ -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 ()
diff --git a/man3/ttyname.3 b/man3/ttyname.3
index 93932610b5..cd98315227 100644
--- a/man3/ttyname.3
+++ b/man3/ttyname.3
@@ -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
diff --git a/man3/unlockpt.3 b/man3/unlockpt.3
index 26333ef6d3..c3d67f4a2c 100644
--- a/man3/unlockpt.3
+++ b/man3/unlockpt.3
@@ -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.
diff --git a/man4/pts.4 b/man4/pts.4
index 0b0682433f..8897c924a8 100644
--- a/man4/pts.4
+++ b/man4/pts.4
@@ -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
diff --git a/man7/pty.7 b/man7/pty.7
index ecc1a6bec6..e8b6c95391 100644
--- a/man7/pty.7
+++ b/man7/pty.7
@@ -26,36 +26,39 @@
 .SH NAME
 pty \- pseudoterminal interfaces
 .SH DESCRIPTION
-A pseudoterminal (sometimes abbreviated "pty")
+A pseudoterminal (sometimes abbreviated "pty") device pair
 is a pair of virtual character devices that
 provide a bidirectional communication channel.
 One end of the channel is called the
-.IR master ;
+.IR "pseudoterminal device" ;
 the other end is called the
-.IR slave .
+.IR "terminal device" .
 .PP
-The slave end of the pseudoterminal provides an interface
+The terminal end of the device pair provides an interface
 that behaves exactly like a classical terminal.
-A process that expects to be connected to a terminal,
-can open the slave end of a pseudoterminal and
-then be driven by a program that has opened the master end.
-Anything that is written on the master end is provided to the process
-on the slave end as though it was input typed on a terminal.
+A process that expects to be connected to a terminal
+can open the terminal end of a pseudoterminal device pair and
+then be driven by a program that has opened the pseudoterminal end
+of the device pair.
+Anything that is written on the pseudoterminal end is provided to the process
+on the terminal end as though it was input typed on a terminal.
 For example, writing the interrupt character (usually control-C)
-to the master device would cause an interrupt signal
+to the pseudoterminal end of the device pair would cause an interrupt signal
 .RB ( SIGINT )
 to be generated for the foreground process group
-that is connected to the slave.
-Conversely, anything that is written to the slave end of the
-pseudoterminal can be read by the process that is connected to
-the master end.
+that is connected to the terminal end.
+Conversely, anything that is written to the terminal end of the
+device pair can be read by the process that is connected to
+the pseudoterminal end.
 .PP
-Data flow between master and slave is handled asynchronously,
+Data flow between the two ends of the device pair is handled asynchronously,
 much like data flow with a physical terminal.
-Data written to the slave will be available at the master promptly,
+Data written to the terminal end will be available at
+the pseudoterminal end promptly,
 but may not be available immediately.
 Similarly, there may be a small processing delay between
-a write to the master, and the effect being visible at the slave.
+a write to the pseudoterminal end,
+and the effect being visible at the terminal end.
 .PP
 Historically, two pseudoterminal APIs have evolved: BSD and System V.
 SUSv1 standardized a pseudoterminal API based on the System V API,
@@ -75,18 +78,18 @@ option.
 that option is disabled by default in the mainline kernel.)
 UNIX 98 pseudoterminals should be used in new applications.
 .SS UNIX 98 pseudoterminals
-An unused UNIX 98 pseudoterminal master is opened by calling
+An unused UNIX 98 pseudoterminal device is opened by calling
 .BR posix_openpt (3).
-(This function opens the master clone device,
+(This function opens the pseudoterminal multiplexor device,
 .IR /dev/ptmx ;
 see
 .BR pts (4).)
 After performing any program-specific initializations,
-changing the ownership and permissions of the slave device using
+changing the ownership and permissions of the terminal device using
 .BR grantpt (3),
-and unlocking the slave using
+and unlocking the terminal using
 .BR unlockpt (3)),
-the corresponding slave device can be opened by passing
+the corresponding terminal device can be opened by passing
 the name returned by
 .BR ptsname (3)
 in a call to
@@ -110,9 +113,9 @@ For further details on these two files, see
 BSD-style pseudoterminals are provided as precreated pairs, with
 names of the form
 .I /dev/ptyXY
-(master) and
+(pseudoterminal) and
 .I /dev/ttyXY
-(slave),
+(corresponding terminal),
 where X is a letter from the 16-character set [p\-za\-e],
 and Y is a letter from the 16-character set [0\-9a\-f].
 (The precise range of letters in these two sets varies across UNIX
@@ -124,22 +127,22 @@ and
 constitute a BSD pseudoterminal pair.
 A process finds an unused pseudoterminal pair by trying to
 .BR open (2)
-each pseudoterminal master until an open succeeds.
-The corresponding pseudoterminal slave (substitute "tty"
-for "pty" in the name of the master) can then be opened.
+each pseudoterminal device until an open succeeds.
+The corresponding terminal device (substitute "tty"
+for "pty" in the name of the pseudoterminal device) can then be opened.
 .SH FILES
 .TP
 .I /dev/ptmx
-UNIX 98 master clone device
+UNIX 98 pseudoterminal multiplexor device
 .TP
 .I /dev/pts/*
-UNIX 98 slave devices
+UNIX 98 terminal devices
 .TP
 .I /dev/pty[p\-za\-e][0\-9a\-f]
-BSD master devices
+The BSD pseudoterminal devices
 .TP
 .I /dev/tty[p\-za\-e][0\-9a\-f]
-BSD slave devices
+The corresponding BSD terminal devices
 .SH NOTES
 Pseudoterminals are used by applications such as network login services
 .RB ( ssh "(1), " rlogin "(1), " telnet (1)),