illumos: manual page: posix

POSIX_OPENPT(3C) Standard C Library Functions POSIX_OPENPT(3C)

NAME

posix_openpt - open a pseudo-terminal manager device

SYNOPSIS

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

int
posix_openpt(int oflag);

DESCRIPTION

The posix_openpt() function establishes a connection between a manager
device for a pseudo-terminal and a file descriptor. The file descriptor is
used by other I/O functions that refer to that pseudo-terminal.

The file status flags and file access modes of the open file description
are set according to the value of oflag.

Values for oflag are constructed by a bitwise-inclusive OR of flags from
the following list, defined in fcntl.h(3HEAD):

O_RDWR Open for reading and writing.

O_NOCTTY
If set, posix_openpt() does not cause the terminal device to become
the controlling terminal for the process.

The behavior of other values for the oflag argument is unspecified.

RETURN VALUES

The posix_getopt() function opens a manager pseudo-terminal device and, if
successful, returns a non-negative integer representing the lowest numbered
unused file descriptor ; otherwise, the value -1 is returned and the global
variable errno is set to indicate the error.

EXAMPLES

Example 1 Open a pseudo-terminal.

The following example opens a pseudo-terminal and returns the name of the
subsidiary device and a file descriptor.

#include <fcntl.h>
#include <stdio.h>
#include <err.h>

int managerfd, subsidiaryfd;
char *subsidiarydevice;

if ((managerfd = posix_openpt(O_RDWR|O_NOCTTY)) < 0) {
err(1, "opening pseudo-terminal manager");
}

if (grantpt(managerfd) != 0 ||
unlockpt(managerfd) != 0 ||
(subsidiarydevice = ptsname(managerfd)) == NULL) {
(void) close(managerfd);
err(1, "locating pseudo-terminal subsidiary");
}

printf("subsidiary device is: %s\n", subsidiarydevice);

if ((subsidiaryfd = open(subsidiary, O_RDWR|O_NOCTTY)) < 0) {
err(1, "opening pseudo-terminal subsidiary");
}

ERRORS

The posix_openpt() function will fail if:

EMFILE {OPEN_MAX} file descriptors are currently open in the
calling process.

ENFILE The maximum allowable number of files is currently open
in the system.

The posix_openpt() function may fail if:

EINVAL The value of oflag is not valid.

EAGAIN The system has run out of pseudo-terminal resources.

ENOSR The system has run out of STREAMS resources.

USAGE

This function provides a portable method for obtaining the file descriptor
of a manager terminal device for a pseudo-terminal, as opposed to using
open(2) on the ptm(4D) device which is system-specific.

The grantpt(3C) function can be used to manipulate the mode and ownership
permissions of the subsidiary device. The ptsname(3C) function can be used
to obtain the name of the subsidiary device.

INTERFACE STABILITY

Committed

MT LEVEL

MT-Safe