pty

NAME

SYNTAX

DESCRIPTION

There are a few very common invocations of pty. The most common is just pty program, with no options; this has several effects as described below. pty -s program sets up a disconnectable session; it is described further in sess(1). pty -0 program isolates the rest of the world from program in several ways; it is described further in condom(1).

The two next most commonly used options are if pty is started without a controlling terminal; and which makes an entry in /etc/utmp.

Some programs (such as vi) don't like taking input or output from a pipe; under pty, they won't notice a thing. Other programs buffer as much output as possible if they're in a pipe; under pty, they'll buffer at most a line of output. pty is very careful to restore terminal modes upon stopping or exiting; a careless program is shielded from your terminal. Otherwise, pty program should feel just like program.

pty changes the original terminal to character-at-a-time (raw, cbreak, and noecho) mode; it sets the pseudo-terminal to the original mode. When program finishes, pty will set the original terminal back to its original mode. Any mode changes on the pseudo-terminal will be lost.

pty sets file descriptor 0 to input from the pseudo-terminal, 1 and 2 to output. pty also supports the ``3 is /dev/tty'' convention: it sets up file descriptor 3 for input from, output to, and terminal commands for /dev/tty (not the original tty, but the pseudo tty).

Options ACHUVW print the authorship notice, copyright notice, help notice, short usage summary, version number, and warranty information respectively.

pty has quite a few flags, processed left to right:

-d

pty will assume it is already detached from the terminal. This forces it sets but doesn't force Also, instead of copying pseudo-terminal modes from the original terminal, pty will set up a generic new-discipline line-at-a-time mode.

-D

pty will assume that it is attached to a terminal (default). This sets

-e

Preserve standard error (file descriptor 2) and standard tty (file descriptor 3).

-3

Preserve fd 3, but point fd 2 at the pseudo-terminal.

-E

Direct both file descriptors to the pseudo-terminal (default). (Actually, pty will point standard error at the tty by name, but fd 3 at /dev/tty, so that various ioctl() commands on fd 3 will work.) Also close all higher-numbered file descriptors.

-j

Job control (default): When program stops, pty stops. When pty is restarted, it restarts program.

-J

No job control. If program stops, pty will ignore it (though it will always restart it upon a reconnect). This behavior is much less antisocial than the behavior of the previous pty version.

-t

pty will set the original terminal to no-echo, character-at-a-time mode (default).

-T

pty will not touch the original terminal, if there is one. It is always dangerous to put two programs in a pipe if both change tty modes; pty, vi, and more are examples of such programs. If you use pty in a pipe with another tty-mode-changing program, make sure to specify (which is an abbreviation for so that pty will neither affect nor be affected by the other program. If you use a pipe of ptys, you should probably specify in all but one.

-s

Session. When the connection is hung up or manually disconnected, pty will patiently wait for a reconnection. program won't notice a thing. sets but does not force It forces

-S

No session (default). When the connection is hung up, pty will send a HUP to program. sets but does not force

-q

Quiet. pty will print absolutely nothing on standard error. It will communicate strange events through its exit code.

-Q

Not quiet (default). pty will generate bits of chatter about interesting events.

-v

Verbose. pty will blabber on and on and on and on and on and on and on and on. It keeps going, and going, and going, and going ...

-ffd

Pass the master and slave sides of the pseudo-terminal up in file descriptor fd. This is only available if your machine supports descriptor passing.

The protocol, from the point of view of the receiver (``controller''), is to pty_getch a character off the other side of the passing descriptor, perhaps check that it is a G, and pty_putgetint a G for the process id of the signaller (the process to recieve a HUP if the connection drops); pty_getch a character, perhaps check that it is m, and pty_putgetfd an m for the master side of the pseudo-terminal; and similarly for s and the slave side. (These functions are all available in sock.c in the pty source code.)

When the connection is dropped, pty will send up a period, followed by one pid and two new descriptors as above if it reconnects. In the meantime, the controller has full responsibility for performing terminal I/O.

-F

Do not pass anything (default).

-pmmm

Set the pseudo-terminal to modes specified by m. Under defaults are taken from the current terminal; under defaults are as below. Predefined modes:

c

Set cbreak (character-at-a-time) mode.

C

Do not set cbreak mode (default).

d

Use the new discipline (default, breaking with tradition).

D

Use the old discipline, without job control or other fancy tty features.

e

Echo characters (default).

E

Do not echo.

n

Change return to newline (default).

N

Do not change return to newline.

r

Set raw mode: do not produce signals, and pass eight-bit characters.

R

Set non-raw (``cooked'') mode (default).

s

Set line editing modes appropriate for a screen (default).

S

Do not set crt line editing modes.

0

An abbreviation for pcEN.

-xsss

Use security, experimental, or extended measures specified by s. Some of these may be required or disabled by your system administrator. Predefined values:

c

Change the ownership and protections of the pty appropriately. This reflects several errors in the pty model, but it's customary.

C

Do not change pty ownership (default).

e

Open stderr write-only to the pseudo-terminal. This should be default, but such programs as csh and more insist on reading from stderr and dying horribly if they fail. is useless under

E

Open stderr for reading and writing (default).

u

Enter login name into /etc/utmp. As a rule of thumb, you should do this for interactive sessions.

n

Use some heuristics to try to figure out if someone has the pty open (default).

N

Don't worry about pre-opened ptys.

o

Same as but go on to the next pseudo-terminal if this one is open.

O

Don't skip pre-opened ptys.

r

Random pseudo-terminal searching (default). This can provide a huge boost to speed and security. It hasn't been used because programmers don't realize the virtues of modularity, are consequently too lazy to write something like pty, and don't want to take the effort for random pty searching in every program that uses pseudo-terminals.

R

Straight pty searching, from the bottom on up.

s

Setuid (default). pty will use a common directory for storing session information.

S

Not setuid. pty will revoke all privileges and use a subdirectory of your HOME directory.

U

Do not use utmp (default).

w

Make an entry in /usr/adm/wtmp. This probably isn't a good idea for general use, as connection time recorded in wtmp is often pressed into unfortunate service as a senseless basis for charged computer time.

W

Do not use wtmp (default).

x

Set exclusive use on the pty. No processes can open the pty after this; program can't even reopen /dev/tty! (It can use file descriptor 3 instead.) This can be very important for security when pty has not been installed by the system administrator. It should be set all the time, but too many programs rely on a filename for the terminal.

X

Do not set exclusive use (default).

DIAGNOSTICS

various usage messages

Exit 1.

fatal: cannot find control terminal

pty is unable to find its current control terminal. Exit 2.

fatal: cannot get current tty modes

This shouldn't happen. Exit 3.

fatal: cannot set modes of original tty

This shouldn't happen. Exit 4.

fatal: no ptys available

Self-explanatory. Exit 5.

fatal: can't fcntl pty

fatal: slave unopenable

There's a serious problem with your pseudo-terminal setup. Report this error to your system administrator. Exit 6.

fatal: cannot fork

pty has run out of processes. Exit 7.

fatal: cannot change to session directory

Self-explanatory. Exit 8.

fatal: cannot open internal pipe.

Cannot happen. Exit 10.

fatal: socket read error

Self-explanatory. Exit 11.

fatal: socket write error

Self-explanatory. Exit 12.

fatal: input read error

Self-explanatory. Exit 13.

fatal: output write error

Self-explanatory. Exit 14.

RESTRICTIONS

The current behavior is a bit dull. I wish programs would use the job control mechanisms more cleanly.

To avoid a race condition, pty chews up a tiny bit more CPU time than it should every time program is stopped and then restarted.

If program closes the pseudo-terminal but doesn't die, pty will wait for it, even though it will have no further interaction with it.

pty does not provide any way to loudly proclaim that program doesn't exist. It simply dies quietly.

Because of BSD's ridiculous controlling terminal mechanism, a reconnecting pty has to pass the name of its original terminal to the session underneath. Since there is no portable way to find out that name, pty requires that some file descriptor be open, pointing to the current terminal (not /dev/tty!). (More precisely, the highest-numbered file descriptor that is a terminal file but not /dev/tty must be the real name of the original controlling terminal. That's one good use for fd 3. If that file descriptor is some other terminal, the reconnect will fail miserably.)  

BUGS

MACHINES

VERSION

AUTHOR

SEE ALSO

Index

NAME

SYNTAX

DESCRIPTION

DIAGNOSTICS

RESTRICTIONS

BUGS

MACHINES

VERSION

AUTHOR

SEE ALSO