---
name: "pty"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/forkpty"
---

# pty(3)

auxiliary functions to obtain a pseudo-terminal

Part of [forkpty(3)](/forkpty/3.md).

## NAME

**openpty**, **forkpty** – auxiliary functions to obtain a pseudo-terminal

## LIBRARY

System Utilities Library (libutil, -lutil)

## SYNOPSIS

**#include \<sys/types.h\>**

**#include \<sys/ioctl.h\>**

**#include \<termios.h\>**

**#include \<libutil.h\>**

*int*\

**openpty**(*int \*amaster*, *int \*aslave*, *char \*name*, *struct termios \*termp*, *struct winsize \*winp*);

*int*\

**forkpty**(*int \*amaster*, *char \*name*, *struct termios \*termp*, *struct winsize \*winp*);

## DESCRIPTION

The function **openpty**() attempts to obtain the next available pseudo-terminal from the system (see [pty(4)](/pty/4.md)). If it successfully finds one, it subsequently changes the ownership of the slave device to the real UID of the current process, the group membership to the group “tty” (if such a group exists in the system), the access permissions for reading and writing by the owner, and for writing by the group, and invalidates any current use of the line by calling [revoke(2)](/revoke/2.md).

If the argument *name* is not NULL, **openpty**() copies the pathname of the slave pty to this area. The caller is responsible for allocating the required space in this array.

If the arguments *termp* or *winp* are not NULL, **openpty**() initializes the termios and window size settings from the structures these arguments point to, respectively.

Upon return, the open file descriptors for the master and slave side of the pty are returned in the locations pointed to by *amaster* and *aslave*, respectively.

The **forkpty**() function first calls **openpty**() to obtain the next available pseudo-terminal from the system. Upon success, it forks off a new process. In the child process, it closes the descriptor for the master side of the pty, and calls [login\_tty(3)](/login_tty/3.md) for the slave pty. In the parent process, it closes the descriptor for the slave side of the pty. The arguments *amaster*, *name*, *termp*, and *winp* have the same meaning as described for **openpty**().

## RETURN VALUES

The **openpty**() function returns 0 on success, or -1 on failure.

The **forkpty**() function returns -1 on failure, 0 in the slave process, and the process ID of the slave process in the parent process.

## ERRORS

The **openpty**() function may fail and set the global variable errno for any of the errors specified for the [grantpt(3)](/grantpt/3.md), [posix\_openpt(2)](/posix_openpt/2.md), [ptsname(3)](/ptsname/3.md), and [unlockpt(3)](/unlockpt/3.md) functions and the [revoke(2)](/revoke/2.md) system call.

In addition to this, **forkpty**() may set it to any value as described for [fork(2)](/fork/2.md).

## SEE ALSO

[chmod(2)](/chmod/2.md), [chown(2)](/chown/2.md), [fork(2)](/fork/2.md), [getuid(2)](/getuid/2.md), [open(2)](/open/2.md), [revoke(2)](/revoke/2.md), [login\_tty(3)](/login_tty/3.md), [pty(4)](/pty/4.md), [termios(4)](/termios/4.md), [group(5)](/group/5.md)

## HISTORY

The **openpty**() and **forkpty**() functions first appeared in 4.3BSD-Reno.

## BUGS

**openpty**() writes the slave terminal's name to *name*, but does not check that sufficient space is available. It is advisable to use [ptsname(3)](/ptsname/3.md) instead.