| 1 |
.\" Copyright 2005, Michael Kerrisk <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH pty 7 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
pty \- pseudoterminal interfaces |
| 9 |
.SH DESCRIPTION |
| 10 |
A pseudoterminal (sometimes abbreviated "pty") |
| 11 |
is a pair of virtual character devices that |
| 12 |
provide a bidirectional communication channel. |
| 13 |
One end of the channel is called the |
| 14 |
.IR master ; |
| 15 |
the other end is called the |
| 16 |
.IR slave . |
| 17 |
.P |
| 18 |
The slave end of the pseudoterminal provides an interface |
| 19 |
that behaves exactly like a classical terminal. |
| 20 |
A process that expects to be connected to a terminal, |
| 21 |
can open the slave end of a pseudoterminal and |
| 22 |
then be driven by a program that has opened the master end. |
| 23 |
Anything that is written on the master end is provided to the process |
| 24 |
on the slave end as though it was input typed on a terminal. |
| 25 |
For example, writing the interrupt character (usually control-C) |
| 26 |
to the master device would cause an interrupt signal |
| 27 |
.RB ( SIGINT ) |
| 28 |
to be generated for the foreground process group |
| 29 |
that is connected to the slave. |
| 30 |
Conversely, anything that is written to the slave end of the |
| 31 |
pseudoterminal can be read by the process that is connected to |
| 32 |
the master end. |
| 33 |
.P |
| 34 |
Data flow between master and slave is handled asynchronously, |
| 35 |
much like data flow with a physical terminal. |
| 36 |
Data written to the slave will be available at the master promptly, |
| 37 |
but may not be available immediately. |
| 38 |
Similarly, there may be a small processing delay between |
| 39 |
a write to the master, and the effect being visible at the slave. |
| 40 |
.P |
| 41 |
Historically, two pseudoterminal APIs have evolved: BSD and System V. |
| 42 |
SUSv1 standardized a pseudoterminal API based on the System V API, |
| 43 |
and this API should be employed in all new programs that use |
| 44 |
pseudoterminals. |
| 45 |
.P |
| 46 |
Linux provides both BSD-style and (standardized) System V-style |
| 47 |
pseudoterminals. |
| 48 |
System V-style terminals are commonly called UNIX 98 pseudoterminals |
| 49 |
on Linux systems. |
| 50 |
.P |
| 51 |
Since Linux 2.6.4, BSD-style pseudoterminals are considered deprecated: |
| 52 |
support can be disabled when building the kernel by disabling the |
| 53 |
.B CONFIG_LEGACY_PTYS |
| 54 |
option. |
| 55 |
(Starting with Linux 2.6.30, |
| 56 |
that option is disabled by default in the mainline kernel.) |
| 57 |
UNIX 98 pseudoterminals should be used in new applications. |
| 58 |
.SS UNIX 98 pseudoterminals |
| 59 |
An unused UNIX 98 pseudoterminal master is opened by calling |
| 60 |
.BR posix_openpt (3). |
| 61 |
(This function opens the master clone device, |
| 62 |
.IR /dev/ptmx ; |
| 63 |
see |
| 64 |
.BR pts (4).) |
| 65 |
After performing any program-specific initializations, |
| 66 |
changing the ownership and permissions of the slave device using |
| 67 |
.BR grantpt (3), |
| 68 |
and unlocking the slave using |
| 69 |
.BR unlockpt (3)), |
| 70 |
the corresponding slave device can be opened by passing |
| 71 |
the name returned by |
| 72 |
.BR ptsname (3) |
| 73 |
in a call to |
| 74 |
.BR open (2). |
| 75 |
.P |
| 76 |
The Linux kernel imposes a limit on the number of available |
| 77 |
UNIX 98 pseudoterminals. |
| 78 |
Up to and including Linux 2.6.3, this limit is configured |
| 79 |
at kernel compilation time |
| 80 |
.RB ( CONFIG_UNIX98_PTYS ), |
| 81 |
and the permitted number of pseudoterminals can be up to 2048, |
| 82 |
with a default setting of 256. |
| 83 |
Since Linux 2.6.4, the limit is dynamically adjustable via |
| 84 |
.IR /proc/sys/kernel/pty/max , |
| 85 |
and a corresponding file, |
| 86 |
.IR /proc/sys/kernel/pty/nr , |
| 87 |
indicates how many pseudoterminals are currently in use. |
| 88 |
For further details on these two files, see |
| 89 |
.BR proc (5). |
| 90 |
.SS BSD pseudoterminals |
| 91 |
BSD-style pseudoterminals are provided as precreated pairs, with |
| 92 |
names of the form |
| 93 |
.I /dev/ptyXY |
| 94 |
(master) and |
| 95 |
.I /dev/ttyXY |
| 96 |
(slave), |
| 97 |
where X is a letter from the 16-character set [p\-za\-e], |
| 98 |
and Y is a letter from the 16-character set [0\-9a\-f]. |
| 99 |
(The precise range of letters in these two sets varies across UNIX |
| 100 |
implementations.) |
| 101 |
For example, |
| 102 |
.I /dev/ptyp1 |
| 103 |
and |
| 104 |
.I /dev/ttyp1 |
| 105 |
constitute a BSD pseudoterminal pair. |
| 106 |
A process finds an unused pseudoterminal pair by trying to |
| 107 |
.BR open (2) |
| 108 |
each pseudoterminal master until an open succeeds. |
| 109 |
The corresponding pseudoterminal slave (substitute "tty" |
| 110 |
for "pty" in the name of the master) can then be opened. |
| 111 |
.SH FILES |
| 112 |
.TP |
| 113 |
.I /dev/ptmx |
| 114 |
UNIX 98 master clone device |
| 115 |
.TP |
| 116 |
.I /dev/pts/* |
| 117 |
UNIX 98 slave devices |
| 118 |
.TP |
| 119 |
.I /dev/pty[p\-za\-e][0\-9a\-f] |
| 120 |
BSD master devices |
| 121 |
.TP |
| 122 |
.I /dev/tty[p\-za\-e][0\-9a\-f] |
| 123 |
BSD slave devices |
| 124 |
.SH NOTES |
| 125 |
Pseudoterminals are used by applications such as network login services |
| 126 |
(\c |
| 127 |
.BR ssh (1), |
| 128 |
.BR rlogin (1), |
| 129 |
.BR telnet (1)), |
| 130 |
terminal emulators such as |
| 131 |
.BR xterm (1), |
| 132 |
.BR script (1), |
| 133 |
.BR screen (1), |
| 134 |
.BR tmux (1), |
| 135 |
.BR unbuffer (1), |
| 136 |
and |
| 137 |
.BR expect (1). |
| 138 |
.P |
| 139 |
A description of the |
| 140 |
.B TIOCPKT |
| 141 |
.BR ioctl (2), |
| 142 |
which controls packet mode operation, can be found in |
| 143 |
.BR ioctl_tty (2). |
| 144 |
.P |
| 145 |
The BSD |
| 146 |
.BR ioctl (2) |
| 147 |
operations |
| 148 |
.BR TIOCSTOP , |
| 149 |
.BR TIOCSTART , |
| 150 |
.BR TIOCUCNTL , |
| 151 |
and |
| 152 |
.B TIOCREMOTE |
| 153 |
have not been implemented under Linux. |
| 154 |
.SH SEE ALSO |
| 155 |
.BR ioctl_tty (2), |
| 156 |
.BR select (2), |
| 157 |
.BR setsid (2), |
| 158 |
.BR forkpty (3), |
| 159 |
.BR openpty (3), |
| 160 |
.BR termios (3), |
| 161 |
.BR pts (4), |
| 162 |
.BR tty (4) |