mirror of https://github.com/mkerrisk/man-pages
160 lines
5.2 KiB
Groff
160 lines
5.2 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" Copyright (C) 2005 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.TH PTY 7 2005-10-10 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
pty \- pseudo-terminal interfaces
|
|
.SH DESCRIPTION
|
|
A pseudo-terminal 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 pseudo-terminal 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 pseudo-terminal 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
|
|
pseudo-terminal can be read by the process that is connected to
|
|
the master end.
|
|
Pseudo-terminals are used by applications such as network login services
|
|
.RB ( ssh "(1), " rlogin "(1), " telnet (1)),
|
|
terminal emulators,
|
|
.BR script (1),
|
|
.BR screen (1),
|
|
and
|
|
.BR expect (1).
|
|
|
|
Historically, two pseudo-terminal APIs have evolved: BSD and System V.
|
|
SUSv1 standardized a pseudo-terminal API based on the System V API,
|
|
and this API should be employed in all new programs that use
|
|
pseudo-terminals.
|
|
|
|
Linux provides both BSD-style and (standardized) System V-style
|
|
pseudo-terminals.
|
|
System V-style terminals are commonly called Unix 98 pseudo-terminals
|
|
on Linux systems.
|
|
Since kernel 2.6.4, BSD-style pseudo-terminals are considered deprecated
|
|
(they can be disabled when configuring the kernel);
|
|
Unix 98 pseudo-terminals should be used in new applications.
|
|
.SS "Unix 98 pseudo-terminals"
|
|
An unused Unix 98 pseudo-terminal 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 pseudo-terminals.
|
|
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 pseudo-terminals 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 pseudo-terminals are currently in use.
|
|
For further details on these two files, see
|
|
.BR proc (5).
|
|
.SS "BSD pseudo-terminals"
|
|
BSD-style pseudo-terminals 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 pseudo-terminal pair.
|
|
A process finds an unused pseudo-terminal pair by trying to
|
|
.BR open (2)
|
|
each pseudo-terminal master until an open succeeds.
|
|
The corresponding pseudo-terminal 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 tty_ioctl (4).
|
|
|
|
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 select (2),
|
|
.BR setsid (2),
|
|
.BR forkpty (3),
|
|
.BR openpty (3),
|
|
.BR termios (3),
|
|
.BR pts (4),
|
|
.BR tty (4),
|
|
.BR tty_ioctl (4)
|