---
name: "openpty"
section: "3"
platform: "macos"
package: "Libc"
version: "1752.120.2"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/openpty"
---

# openpty(3)

tty utility functions

## NAME

**openpty**, **login\_tty**, **forkpty** – tty utility functions

## SYNOPSIS

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

## DESCRIPTION

The **openpty**(), **login\_tty**(), and **forkpty**() functions manipulate ttys and pseudo-ttys.

The **openpty**() 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 **login\_tty**() 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 **forkpty**() function combines **openpty**(), **fork**(), 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.

## RETURN VALUES

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.

## ERRORS

**openpty**() will fail if:

- \[EAGAIN\]

  There are no available pseudo-ttys.

- \[ENXIO\]

  The [sysctl(3)](/sysctl/3.md) 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)](/open/2.md) 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.

## FILES

- */dev/ptmx*

  cloning pseudo-tty device

- */dev/ttys\[0-9\]\[0-9\]\[0-9\]*

  replica pseudo-tty devices

## SEE ALSO

[fork(2)](/fork/2.md), [ptsname(3)](/ptsname/3.md), [sysctl(3)](/sysctl/3.md)

## CAVEATS

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)](/ptsname_r/3.md) instead.