| .\" Copyright (C) 2005 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH PTY 7 2015-07-23 "Linux" "Linux Programmer's Manual" |
| .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 . |
| 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. |
| Pseudoterminals are used by applications such as network login services |
| .RB ( ssh "(1), " rlogin "(1), " 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). |
| |
| 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. |
| |
| 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. |
| |
| Linux provides both BSD-style and (standardized) System V-style |
| pseudoterminals. |
| System V-style terminals are commonly called UNIX 98 pseudoterminals |
| on Linux systems. |
| Since kernel 2.6.4, BSD-style pseudoterminals are considered deprecated |
| (they can be disabled when configuring the 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). |
| |
| The Linux kernel imposes a limit on the number of available |
| UNIX 98 pseudoterminals. |
| In kernels up to and including 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 kernel 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 |
| .I /dev/ptmx |
| (UNIX 98 master clone device) |
| .br |
| .I /dev/pts/* |
| (UNIX 98 slave devices) |
| .br |
| .I /dev/pty[p-za-e][0-9a-f] |
| (BSD master devices) |
| .br |
| .I /dev/tty[p-za-e][0-9a-f] |
| (BSD slave devices) |
| .SH NOTES |
| A description of the |
| .B TIOCPKT |
| .BR ioctl (2), |
| which controls packet mode operation, can be found in |
| .BR ioctl_tty (2). |
| |
| The BSD |
| .BR ioctl (2) |
| operations |
| .BR TIOCSTOP , |
| .BR TIOCSTART , |
| .BR TIOCUCNTL , |
| and |
| .BR 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) |