Tribblix: 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_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