Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

forkpty (3C)

Name

openpty, login_tty, forkpty - terminal utility functions

Synopsis

#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);

Description

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.

Return Values

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.

Errors

The openpty() function will fail if:

EMFILE

OPEN_MAX file descriptors are currently open in the calling process

ENFILE

The maximum allowable number of files are currently open in the system

EAGAIN

Out of pseudo-terminal resources

EACCES

The corresponding slave pseudo-terminal device could not be accessed

The login_tty() function will fail if:

EPERM

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

EBADF

The fildes argument is not a valid open file descriptor

EMFILE

The process has too many files open. For more information, see the getrlimit man page

ENOLINK

The fildes argument is on a remote machine and the link to that machine is no longer active

The forkpty() function will fail if:

EAGAIN

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

ENOMEM

There is not enough swap space

EPERM

The PRIV_PROC_FORK privilege is not asserted in the effective set of the calling process

Files

/dev/ptmx

Master clone device

/dev/pts/M

Slave devices (M = 0 -> N-1)

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Safe

See Also

pty(4D), pts(4D), posix_openpt(3C), grantpt(3C), unlockpt(3C), ptsname(3C), getrlimit(2)