pty

Section: User Commands (1)
Index Return to Main Contents

NAME

pty - run a program under a pseudo-terminal session

SYNTAX

pty [ -qQve3EdDjJsStTrR0 ] [ -hhost ] [ -Oremote ] [ -p[cCdDeEnNrRsS780] ] [ -x[cCeEfFrRsSuUwWxX] ] [ -ACHUVW ] program [ arg ... ]

DESCRIPTION

pty detaches itself from its original terminal, allocates a new pseudo-terminal session, and runs program on that pseudo-terminal with any given arguments. pty lets you easily disconnect from and reconnect to sessions; it has over fifty options for precise control, and is meant to act as the sole interface between pseudo-terminals and the rest of the system.

pty transmits I/O and job control transparently, so that (for instance) pty vi appears to the user to be the same as vi, but in fact pty is much more flexible. pty vi can be redirected, for example, while a simple vi cannot. pty has several other uses, as described below.

There are a few very common invocations of pty. The most common is just pty program, with no options. As described in the pty-basic man page, this can be redirected or placed inside a pipeline, and program will behave as if it hadn't been redirected at all. pty -s program sets up a disconnectable session, as described further in the sess(1) man page. A disconnectable session will survive modem hangups, network glitches, etc. It also lets the user disconnect his session at work and reconnect later at home without killing his jobs in progress. pty -0 program isolates the rest of the world from program in several ways; it is described further in the condom(1) man page.

The two next most commonly used options are if pty is started without a controlling terminal; and which makes an entry in /etc/utmp. pty -d is especially useful inside rsh, where interactive programs normally fail for lack of a tty.

As noted above, 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, based on the standard I/O library, buffer as much output as possible if they're in a pipe. Under pty, they'll buffer only a line of output as usual. pty is very careful to restore terminal modes upon stopping or exiting; a careless program is shielded from your terminal. Otherwise, pty program ``feels'' just like program.

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).

pty has many options, as documented in the pty-opts man page.

DIAGNOSTICS

various usage messages: Exit 1.
cannot find controlling tty; try -d?: pty is unable to find its current terminal to copy tty modes from. (This version of pty defines its controlling tty to be the first one of the following which is a tty device: descriptor 3, /dev/tty, descriptor 0, descriptor 1, descriptor 2.) You probably want to use to tell pty to make a pseudo-terminal from scratch. Exit 2.
cannot get modes of original tty: This shouldn't happen. Exit 3.
cannot set modes of original tty: This shouldn't happen. Exit 4.
no ptys available: Self-explanatory. Exit 5.
cannot set up open descriptors: There is a serious problem with your pseudo-terminal setup. Report this error to your system administrator. Exit 6.
cannot fork: pty has run out of processes. Exit 7.
signaller cannot change to session directory: Probably the session directory has not been created with the appropriate modes, or pty is not running with sufficient privilege. Note that this error is often duplicated or triplicated, as the various pieces of pty depend on the session directory for communication, including communication of this error! Exit 8.
out of memory: Self-explanatory. Exit 9.
cannot create internal pipe
cannot setsid: These errors will not happen in my lifetime. If they do, it's probably because of quantum bit flips. Exit 10.
signaller having trouble
signaller cannot read success code from master: Something has gone very wrong with the communications paths inside pty. This should not happen. Exit 11.
session already connected somewhere else: This error can happen upon session reconnect and, in that case, is self-explanatory. Exit 16.
cannot find session; does it exist?: Self-explanatory, again upon session reconnect. Exit 17.
various cannot messages: If something is slightly wrong with the user-supplied environment (for instance, if program does not exist) pty will print an error but will exit 0, as if it had successfully executed a shell script which then detected the error. This is consistent with the way that pty does not report the exit status of program.
warning: cannot write utmp entry: Self-explanatory.
warning: cannot dissociate from current tty: pty is unable to submit to the kernel's controlling tty demands. If, for example, the tty has TIOCEXCL mode set, then there is absolutely no reliable way for a program to dissociate itself from that tty. This may or may not affect program.
warning: no secure ptys available: pty 4.0 comes with security features which, on a standard BSD 4.3-derived system, guarantee that any pseudo-tty used will be completely clean. This message means that no clean ptys are available. (There is an option which will force pty to exit in this case.)
warning: cannot set exclusive use on pseudo-tty: Self-explanatory.

BUGS

None known, but they're probably hiding somewhere.

MANDATORY SERMON

UNIX programs have traditionally allocated pseudo-terminals with the same code copied from one application to the next. Maintaining or adding features to the pseudo-terminal system is nearly impossible, as so many programs depend on its current internals. Porting a program to a new system often means rewriting its pseudo-terminal allocation code. And the reliability and security of the entire system are jeapordized by this decentralized management of one of the UNIX system's most important resources.

pty solves these problems. If programmers use pty instead of writing equivalent code in each program, then everything becomes much more portable and bug-free. The only program that need be changed for a different system with a different pseudo-terminal mechanism is pty. (This is called ``modularity,'' ``interface design,'' or ``outside-in programming.'') pty is small enough to be reasonbly reliable, and it solves the security problems that plague BSD pseudo-ttys. It is the author's opinion that pty is the ``right'' interface between pseudo-ttys and the rest of the system.

VERSION

pty version 4.0, 2/9/92.

AUTHOR

This document was created by man2html, using the manual pages.
Time: 06:20:47 GMT, December 12, 2024

pty