Technical Reference: Base Operating System and Extensions, Volume 1

posix_openpt Subroutine

Purpose

Opens a pseudo-terminal device.

Library

Standard C library (libc.a)

Syntax

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

 int posix_openpt (oflag
)
int oflag;

Description

The posix_openpt subroutine establishes a connection between a master 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 the oflag parameter.

Parameters

oflag

Values for the oflag parameter are constructed by a bitwise-inclusive OR of flags from the following list, defined in the <fcntl.h> file:

O_RDWR: Open for reading and writing.
O_NOCTTY: If set, the posix_openpt subroutine does not cause the terminal device to become the controlling terminal for the process.

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

Return Values

Upon successful completion, the posix_openpt subroutine opens a master pseudo-terminal device and returns a non-negative integer representing the lowest numbered unused file descriptor. Otherwise, -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The posix_openpt subroutine 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 subroutine may fail if:

EINVAL	The value of the oflag parameter is not valid.
EAGAIN	Out of pseudo-terminal resources.
ENOSR	Out of STREAMS resources.

Examples

The following example describes how to open a pseudo-terminal and return the name of the slave device and file descriptor

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

int masterfd, slavefd;
char *slavedevice;

masterfd = posix_openpt(O_RDWR|O_NOCTTY);

if (masterfd == -1
   || grantpt (masterfd) == -1
      || unlockpt (masterfd) == -1
      || (slavedevice = ptsname (masterfd)) == NULL)
      return -1;

printf("slave device is: %s\n", slavedevice);

slavefd = open(slave, O_RDWR|O_NOCTTY);
if (slavefd < 0)
   return -1;

Related Information

grantpt Subroutine, open, openx, open64, creat, or creat64 Subroutine, ptsname Subroutine.

unlockpt Subroutine in AIX 5L Version 5.2 Technical Reference: Base Operating System and Extensions Volume 2.

<fcntl.h> file in AIX 5L Version 5.2 Files Reference.