man7/pty.7

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) 2005 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\"
  25 .TH PTY 7 2005-10-10 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 pty \- psuedoterminal interfaces
  28 .SH DESCRIPTION
  29 A psuedoterminal is a pair of virtual character devices that
  30 provide a bidirectional communication channel.
  31 One end of the channel is called the
  32 .IR master ;
  33 the other end is called the
  34 .IR slave .
  35 The slave end of the psuedoterminal provides an interface
  36 that behaves exactly like a classical terminal.
  37 A process that expects to be connected to a terminal,
  38 can open the slave end of a psuedoterminal and
  39 then be driven by a program that has opened the master end.
  40 Anything that is written on the master end is provided to the process
  41 on the slave end as though it was input typed on a terminal.
  42 For example, writing the interrupt character (usually control-C)
  43 to the master device would cause an interrupt signal
  44 .RB ( SIGINT )
  45 to be generated for the foreground process group
  46 that is connected to the slave.
  47 Conversely, anything that is written to the slave end of the
  48 psuedoterminal can be read by the process that is connected to
  49 the master end.
  50 Psuedoterminals are used by applications such as network login services
  51 .RB ( ssh "(1), " rlogin "(1), " telnet (1)),
  52 terminal emulators,
  53 .BR script (1),
  54 .BR screen (1),
  55 and
  56 .BR expect (1).
  57
  58 Historically, two psuedoterminal APIs have evolved: BSD and System V.
  59 SUSv1 standardized a psuedoterminal API based on the System V API,
  60 and this API should be employed in all new programs that use
  61 psuedoterminals.
  62
  63 Linux provides both BSD-style and (standardized) System V-style
  64 psuedoterminals.
  65 System V-style terminals are commonly called UNIX 98 psuedoterminals
  66 on Linux systems.
  67 Since kernel 2.6.4, BSD-style psuedoterminals are considered deprecated
  68 (they can be disabled when configuring the kernel);
  69 UNIX 98 psuedoterminals should be used in new applications.
  70 .SS "UNIX 98 psuedoterminals"
  71 An unused UNIX 98 psuedoterminal master is opened by calling
  72 .BR posix_openpt (3).
  73 (This function opens the master clone device,
  74 .IR /dev/ptmx ;
  75 see
  76 .BR pts (4).)
  77 After performing any program-specific initializations,
  78 changing the ownership and permissions of the slave device using
  79 .BR grantpt (3),
  80 and unlocking the slave using
  81 .BR unlockpt (3)),
  82 the corresponding slave device can be opened by passing
  83 the name returned by
  84 .BR ptsname (3)
  85 in a call to
  86 .BR open (2).
  87
  88 The Linux kernel imposes a limit on the number of available
  89 UNIX 98 psuedoterminals.
  90 In kernels up to and including 2.6.3, this limit is configured
  91 at kernel compilation time
  92 .RB ( CONFIG_UNIX98_PTYS ),
  93 and the permitted number of psuedoterminals can be up to 2048,
  94 with a default setting of 256.
  95 Since kernel 2.6.4, the limit is dynamically adjustable via
  96 .IR /proc/sys/kernel/pty/max ,
  97 and a corresponding file,
  98 .IR /proc/sys/kernel/pty/nr ,
  99 indicates how many psuedoterminals are currently in use.
 100 For further details on these two files, see
 101 .BR proc (5).
 102 .SS "BSD psuedoterminals"
 103 BSD-style psuedoterminals are provided as precreated pairs, with
 104 names of the form
 105 .I /dev/ptyXY
 106 (master) and
 107 .I /dev/ttyXY
 108 (slave),
 109 where X is a letter from the 16-character set [p-za-e],
 110 and Y is a letter from the 16-character set [0-9a-f].
 111 (The precise range of letters in these two sets varies across UNIX
 112 implementations.)
 113 For example,
 114 .I /dev/ptyp1
 115 and
 116 .I /dev/ttyp1
 117 constitute a BSD psuedoterminal pair.
 118 A process finds an unused psuedoterminal pair by trying to
 119 .BR open (2)
 120 each psuedoterminal master until an open succeeds.
 121 The corresponding psuedoterminal slave (substitute "tty"
 122 for "pty" in the name of the master) can then be opened.
 123 .SH "FILES"
 124 .I /dev/ptmx
 125 (UNIX 98 master clone device)
 126 .br
 127 .I /dev/pts/*
 128 (UNIX 98 slave devices)
 129 .br
 130 .I /dev/pty[p-za-e][0-9a-f]
 131 (BSD master devices)
 132 .br
 133 .I /dev/tty[p-za-e][0-9a-f]
 134 (BSD slave devices)
 135 .SH "NOTES"
 136 A description of the
 137 .B TIOCPKT
 138 .BR ioctl (2),
 139 which controls packet mode operation, can be found in
 140 .BR tty_ioctl (4).
 141
 142 The BSD
 143 .BR ioctl (2)
 144 operations
 145 .BR TIOCSTOP ,
 146 .BR TIOCSTART ,
 147 .BR TIOCUCNTL ,
 148 and
 149 .BR TIOCREMOTE
 150 have not been implemented under Linux.
 151 .SH "SEE ALSO"
 152 .BR select (2),
 153 .BR setsid (2),
 154 .BR forkpty (3),
 155 .BR openpty (3),
 156 .BR termios (3),
 157 .BR pts (4),
 158 .BR tty (4),
 159 .BR tty_ioctl (4)