1 files changed, 161 insertions, 0 deletions
diff --git a/man/man7/pty.7 b/man/man7/pty.7
new file mode 100644
index 0000000..182d279
--- /dev/null
+++ b/man/man7/pty.7
@@ -0,0 +1,161 @@
+.\" Copyright (C) 2005 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pty 7 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+pty \- pseudoterminal interfaces
+.SH DESCRIPTION
+A pseudoterminal (sometimes abbreviated "pty")
+is a pair of virtual character devices that
+provide a bidirectional communication channel.
+One end of the channel is called the
+.IR master ;
+the other end is called the
+.IR slave .
+.P
+The slave end of the pseudoterminal 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.
+For example, writing the interrupt character (usually control-C)
+to the master device 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.
+.P
+Data flow between master and slave is handled asynchronously,
+much like data flow with a physical terminal.
+Data written to the slave will be available at the master 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.
+.P
+Historically, two pseudoterminal APIs have evolved: BSD and System V.
+SUSv1 standardized a pseudoterminal API based on the System V API,
+and this API should be employed in all new programs that use
+pseudoterminals.
+.P
+Linux provides both BSD-style and (standardized) System V-style
+pseudoterminals.
+System V-style terminals are commonly called UNIX 98 pseudoterminals
+on Linux systems.
+.P
+Since Linux 2.6.4, BSD-style pseudoterminals are considered deprecated:
+support can be disabled when building the kernel by disabling the
+.B CONFIG_LEGACY_PTYS
+option.
+(Starting with Linux 2.6.30,
+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
+.BR posix_openpt (3).
+(This function opens the master clone device,
+.IR /dev/ptmx ;
+see
+.BR pts (4).)
+After performing any program-specific initializations,
+changing the ownership and permissions of the slave device using
+.BR grantpt (3),
+and unlocking the slave using
+.BR unlockpt (3)),
+the corresponding slave device can be opened by passing
+the name returned by
+.BR ptsname (3)
+in a call to
+.BR open (2).
+.P
+The Linux kernel imposes a limit on the number of available
+UNIX 98 pseudoterminals.
+Up to and including Linux 2.6.3, this limit is configured
+at kernel compilation time
+.RB ( CONFIG_UNIX98_PTYS ),
+and the permitted number of pseudoterminals can be up to 2048,
+with a default setting of 256.
+Since Linux 2.6.4, the limit is dynamically adjustable via
+.IR /proc/sys/kernel/pty/max ,
+and a corresponding file,
+.IR /proc/sys/kernel/pty/nr ,
+indicates how many pseudoterminals are currently in use.
+For further details on these two files, see
+.BR proc (5).
+.SS BSD pseudoterminals
+BSD-style pseudoterminals are provided as precreated pairs, with
+names of the form
+.I /dev/ptyXY
+(master) and
+.I /dev/ttyXY
+(slave),
+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
+implementations.)
+For example,
+.I /dev/ptyp1
+and
+.I /dev/ttyp1
+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.
+.SH FILES
+.TP
+.I /dev/ptmx
+UNIX 98 master clone device
+.TP
+.I /dev/pts/*
+UNIX 98 slave devices
+.TP
+.I /dev/pty[p\-za\-e][0\-9a\-f]
+BSD master devices
+.TP
+.I /dev/tty[p\-za\-e][0\-9a\-f]
+BSD slave devices
+.SH NOTES
+Pseudoterminals are used by applications such as network login services
+(\c
+.BR ssh (1),
+.BR rlogin (1),
+.BR telnet (1)),
+terminal emulators such as
+.BR xterm (1),
+.BR script (1),
+.BR screen (1),
+.BR tmux (1),
+.BR unbuffer (1),
+and
+.BR expect (1).
+.P
+A description of the
+.B TIOCPKT
+.BR ioctl (2),
+which controls packet mode operation, can be found in
+.BR ioctl_tty (2).
+.P
+The BSD
+.BR ioctl (2)
+operations
+.BR TIOCSTOP ,
+.BR TIOCSTART ,
+.BR TIOCUCNTL ,
+and
+.B TIOCREMOTE
+have not been implemented under Linux.
+.SH SEE ALSO
+.BR ioctl_tty (2),
+.BR select (2),
+.BR setsid (2),
+.BR forkpty (3),
+.BR openpty (3),
+.BR termios (3),
+.BR pts (4),
+.BR tty (4)