#### 17.10.1 Allocating Pseudo-Terminals ¶

This subsection describes functions for allocating a pseudo-terminal, and for making this pseudo-terminal available for actual use. These functions are declared in the header file `stdlib.h`.

Function: `int` posix_openpt `(int flags)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | See POSIX Safety Concepts.

  `posix_openpt` returns a new file descriptor for the next available master pseudo-terminal. In the case of an error, it returns a value of -1 instead, and sets `errno` to indicate the error. See Opening and Closing Files for possible values of `errno`.

  flags is a bit mask created from a bitwise OR of zero or more of the following flags:

  `O_RDWR`

    Open the device for both reading and writing. It is usual to specify this flag.

  `O_NOCTTY`

    Do not make the device the controlling terminal for the process.

  These flags are defined in `fcntl.h`. See File Access Modes.

  For this function to be available, `_XOPEN_SOURCE` must be defined to a value greater than ‘`600`’. See Feature Test Macros.

Function: `int` getpt `(void)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | See POSIX Safety Concepts.

  `getpt` is similar to `posix_openpt`. This function is a GNU extension and should not be used in portable programs.

  The `getpt` function returns a new file descriptor for the next available master pseudo-terminal. The normal return value from `getpt` is a non-negative integer file descriptor. In the case of an error, a value of -1 is returned instead. The following `errno` conditions are defined for this function:

  `ENOENT`

    There are no free master pseudo-terminals available.

Function: `int` grantpt `(int filedes)` ¶

  Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | See POSIX Safety Concepts.

  The `grantpt` function changes the ownership and access permission of the slave pseudo-terminal device corresponding to the master pseudo-terminal device associated with the file descriptor filedes. The owner is set from the real user ID of the calling process (see The Persona of a Process), and the group is set to a special group (typically tty) or from the real group ID of the calling process. The access permission is set such that the file is both readable and writable by the owner and only writable by the group.

  On some systems this function is implemented by invoking a special `setuid` root program (see How an Application Can Change Persona). As a consequence, installing a signal handler for the `SIGCHLD` signal (see Job Control Signals) may interfere with a call to `grantpt`.

  The normal return value from `grantpt` is 0; a value of -1 is returned in case of failure. The following `errno` error conditions are defined for this function:

  `EBADF`

    The filedes argument is not a valid file descriptor.

  `EINVAL`

    The filedes argument is not associated with a master pseudo-terminal device.

  `EACCES`

    The slave pseudo-terminal device corresponding to the master associated with filedes could not be accessed.

Function: `int` unlockpt `(int filedes)` ¶

  Preliminary: | MT-Safe | AS-Unsafe heap/bsd | AC-Unsafe mem fd | See POSIX Safety Concepts.

  The `unlockpt` function unlocks the slave pseudo-terminal device corresponding to the master pseudo-terminal device associated with the file descriptor filedes. On many systems, the slave can only be opened after unlocking, so portable applications should always call `unlockpt` before trying to open the slave.

  The normal return value from `unlockpt` is 0; a value of -1 is returned in case of failure. The following `errno` error conditions are defined for this function:

  `EBADF`

    The filedes argument is not a valid file descriptor.

  `EINVAL`

    The filedes argument is not associated with a master pseudo-terminal device.

Function: `char *` ptsname `(int filedes)` ¶

  Preliminary: | MT-Unsafe race:ptsname | AS-Unsafe heap/bsd | AC-Unsafe mem fd | See POSIX Safety Concepts.

  If the file descriptor filedes is associated with a master pseudo-terminal device, the `ptsname` function returns a pointer to a statically-allocated, null-terminated string containing the file name of the associated slave pseudo-terminal file. This string might be overwritten by subsequent calls to `ptsname`.

Function: `int` ptsname_r `(int filedes, char *buf, size_t len)` ¶

  Preliminary: | MT-Safe | AS-Unsafe heap/bsd | AC-Unsafe mem fd | See POSIX Safety Concepts.

  The `ptsname_r` function is similar to the `ptsname` function except that it places its result into the user-specified buffer starting at buf with length len.

  This function was originally a GNU extension, but was added in POSIX.1-2024.

Typical usage of these functions is illustrated by the following example:

    int
    open_pty_pair (int *amaster, int *aslave)
    {
      int master, slave;
      char *name;

      master = posix_openpt (O_RDWR | O_NOCTTY);
      if (master < 0)
        return 0;

      if (grantpt (master) < 0 || unlockpt (master) < 0)
        goto close_master;
      name = ptsname (master);
      if (name == NULL)
        goto close_master;

      slave = open (name, O_RDWR);
      if (slave == -1)
        goto close_master;

      *amaster = master;
      *aslave = slave;
      return 1;

    close_slave:
      close (slave);

    close_master:
      close (master);
      return 0;
    }