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_openpt() 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