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

# grantpt(3)

pseudo-terminal access functions

## NAME

**grantpt**, **posix\_openpt**, **ptsname**, **ptsname\_r**, **unlockpt** – pseudo-terminal access functions

## SYNOPSIS

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

*int*\

**grantpt**(*int fildes*);

*char \**\

**ptsname**(*int fildes*);

*int*\

**ptsname\_r**(*int fildes*, *char \*buffer*, *size\_t buflen*);

*int*\

**unlockpt**(*int fildes*);

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

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

*int*\

**posix\_openpt**(*int oflag*);

## DESCRIPTION

The **grantpt**(), **ptsname**(), **ptsname\_r**(), **unlockpt**(), and **posix\_openpt**() functions allow access to pseudo-terminal devices. The first four functions accept a file descriptor that references the primary half of a pseudo-terminal pair. This file descriptor is created with **posix\_openpt**().

The **grantpt**() function is used to establish ownership and permissions of the replica device counterpart to the primary device specified with *fildes*. The replica device's ownership is set to the real user ID of the calling process; its permissions are set to user readable-writable and group writable. The group owner of the replica device is also set to the group “tty” if it exists on the system; otherwise, it is left untouched.

The **ptsname**() function returns a pointer to the full pathname of the replica device counterpart to the primary device specified with *fildes*. This value can be used to subsequently open the appropriate replica after **posix\_openpt**() and **grantpt**() have been called. The **ptsname**() function is not guaranteed to be reentrant or thread safe. The **ptsname\_r**() function stores the full pathname of the replica device in the buffer pointed to by its *buffer* argument, up to a maximum length of *buflen* including the terminating NUL.

The **unlockpt**() function unlocks the replica pseudo-terminal device associated with the primary device to which *fildes* refers.

The **posix\_openpt**() function opens the first available primary pseudo-terminal device and returns a descriptor to it. The *oflag* argument specifies the flags used for opening the device:

- O\_RDWR

  Open for reading and writing.

- O\_NOCTTY

  If set, do not allow the terminal to become the controlling terminal for the calling process.

## RETURN VALUES

The **grantpt()** and **unlockpt()** functions return the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

The **ptsname**() function returns a pointer to the name of the replica device on success; otherwise a NULL pointer is returned and the global variable *errno* is set to indicate the error.

The **ptsname\_r**() function returns 0 if successful. On failure, it returns -1 and the global variable *errno* is set to indicate the error.

The **posix\_openpt**() function returns a file descriptor to the first available primary pseudo-terminal device on success; otherwise -1 is returned and the global variable *errno* is set to indicate the error.

## ERRORS

The **grantpt**(), **ptsname**(), **ptsname\_r**(), and **unlockpt**() functions may fail and set *errno* to:

- \[EINVAL\]

  *fildes* is not a primary pseudo-terminal device.

In addition, the **ptsname\_r**() function may set *errno* to:

- \[EINVAL\]

  The *buffer* argument is NULL.

- \[ERANGE\]

  The *buflen* argument is smaller than the length of the string to be returned, including the terminating NUL.

In addition, the **grantpt**() function may set *errno* to:

- \[EACCES\]

  The replica pseudo-terminal device could not be accessed.

The **posix\_openpt**() function may fail and set *errno* to:

- \[EINVAL\]

  *oflag* consists of an invalid mode bit.

- \[EAGAIN\]

  The system has no available pseudo-terminal devices.

- \[ENXIO\]

  The [sysctl(3)](/sysctl/3.md) limit “kern.tty.ptmx\_max” number of pseudo-terminal devices was reached.

The **grantpt**(), **ptsname**(), **ptsname\_r**(), and **unlockpt**() functions may also fail and set *errno* for any of the errors specified for the [fstat(2)](/fstat/2.md) system call.

The **posix\_openpt**() function may also fail and set *errno* for any of the errors specified for the [open(2)](/open/2.md) system call.

## LEGACY SYNOPSIS

**#include \<stdlib.h\>** **#include \<fcntl.h\>**

*int*\
 **grantpt**(*int fildes*);

*char \**\
 **ptsname**(*int fildes*);

*int*\
 **unlockpt**(*int fildes*);

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

*int*\
 **posix\_openpt**(*int oflag*);

## SEE ALSO

[open(2)](/open/2.md), [sysctl(3)](/sysctl/3.md), [pty(4)](/pty/4.md), [tty(4)](/tty/4.md), [compat(5)](/compat/5.md)

## STANDARDS

The **grantpt**(), **ptsname**(), **unlockpt**(), and **posix\_openpt**() functions conform to IEEE Std 1003.1-2001 (“POSIX.1”).