OPENPTY(3) Library Functions Manual OPENPTY(3)

openpty, login_tty, forkpty — tty utility functions

#include <util.h>

int
openpty(int *aprimary, int *areplica, char *name, struct termios *termp, struct winsize *winp);

int
login_tty(int fd);

pid_t
forkpty(int *aprimary, char *name, struct termios *termp, struct winsize *winp);

The (), login_tty(), and forkpty() functions manipulate ttys and pseudo-ttys.

The () function allocates a pseudo-tty and returns file descriptors for the primary and replica in aprimary and areplica. If name is non-null, the pathname of the replica is stored in the buffer pointed to by name, which must be at least 128 bytes. If termp is non-null, the terminal parameters of the replica will be set to the values in termp. If winp is non-null, the window size of the replica will be set to the values in winp.

The () function prepares for a login on the tty fd (which may be a real tty device, or the replica of a pseudo-tty as returned by openpty()) 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 () function combines openpty(), (), and login_tty() to creates a new process operating in a pseudo-tty. The file descriptor of the primary side of the pseudo-tty is returned in aprimary, and the pathname of the replica is stored in the buffer pointed to by name if it is non-null. The buffer must be at least 128 bytes long. The termp and winp parameters, if non-null, will determine the terminal attributes and window size of the replica side of the pseudo-tty.

If a call to openpty(), login_tty(), or forkpty() is not successful, -1 is returned and errno is set to indicate the error. Otherwise, openpty(), login_tty(), and the child process of forkpty() return 0, and the parent process of forkpty() returns the process ID of the child process.

openpty() will fail if:

[]
There are no available pseudo-ttys.
[]
The sysctl(3) limit “kern.tty.ptmx_max” number of pseudo-terminal devices was reached.

The openpty() function may also fail and set errno for any of the errors specified for the open(2) system call.

login_tty() will fail if ioctl() fails to set fd to the controlling terminal of the current process. forkpty() will fail if either openpty() or fork() fails.

/dev/ptmx
cloning pseudo-tty device
/dev/ttys[0-9][0-9][0-9]
replica pseudo-tty devices

fork(2), ptsname(3), sysctl(3)

Due to the risk of accidentally passing a too-small buffer as the name argument to the forkpty() and openpty() functions, it is advisable to use ptsname_r(3) instead.

June 17, 2025 Mac OS X 14