openpty, login_tty, forkpty - terminal utility functions
#include <termios.h>
int openpty(int *amaster, int *aslave, char *name,
struct termios *termp, struct winsize *winp);
int login_tty(int fd);
pid_t forkpty(int *amaster, char *name, struct termios *termp,
struct winsize *winp);
The openpty(), login_tty(), and forkpty() functions perform manipulations on ttys and pseudo-ttys.
The openpty() function finds an available pseudo-tty and returns file descriptors for the master and slave in amaster and aslave. If name is non-null, the filename of the slave is returned in name, a string of at least 32 characters. If termp is non-null, the terminal parameters of the slave will be set to the values in termp. If winp is non-null, the window size of the slave will be set to the values in winp. The openpty() function first attempts to allocate the pseudo-tty through the /dev/ptmx device using the posix_openpt command. It then invokes the grantpt(), unlockpt(), and ptsname() functions to obtain the path of the pseudo-terminal slave. It opens the pseudo-terminal slave, and attempts to set terminal attribute and window size of the pty slave if termp and winp are valid. Finally, the function returns the pty master fd, pty slave, and pty slave name to the caller. For more information, see pty, ptm and pts man pages.
The login_tty() function prepares for a login on the tty fd, which can either be a real tty device, or a slave of the pseudo-tty as returned by the openpty() function. The function prepares for a login by creating a new session, making fd the controlling terminal for the current process, setting fd to be the standard input, output, and error streams of the current process, and closing fd.
The forkpty() function combines the openpty(), fork(), and login_tty() functions to create a new process attached to a pseudo-tty. The file descriptor of the master side of the pseudo-tty is returned in amaster, and the filename of the slave in name, if it is non-null. The termp and winp parameters, if non-null, will determine the terminal attributes and window size of the slave side of the pseudo-terminal.
If a call to the openpty(), login_tty(), or forkpty() functions is not successful, then -1 is returned, and errno is set to indicate the error. Otherwise, the openpty(), login_tty(), and the child process of the forkpty() functions return 0, and the parent process of forkpty() returns the process ID of the child process.
The openpty() function will fail if:
OPEN_MAX file descriptors are currently open in the calling process
The maximum allowable number of files are currently open in the system
Out of pseudo-terminal resources
The corresponding slave pseudo-terminal device could not be accessed
The login_tty() function will fail if:
The calling process is already a process group leader, or the process group ID of a process other than the calling process matches the process ID of the calling process
The fildes argument is not a valid open file descriptor
The process has too many files open. For more information, see the getrlimit man page
The fildes argument is on a remote machine and the link to that machine is no longer active
The forkpty() function will fail if:
A resource control or limit on the total number of processes, tasks, or LWPs under execution by a single user, task, project, or zone has been exceeded. This error can also occur if the total amount of system memory available is temporarily insufficient to duplicate this process
There is not enough swap space
The PRIV_PROC_FORK privilege is not asserted in the effective set of the calling process
Master clone device
Slave devices (M = 0 -> N-1)
See attributes(7) for descriptions of the following attributes:
|
pty(4D), pts(4D), posix_openpt(3C), grantpt(3C), unlockpt(3C), ptsname(3C), getrlimit(2)