The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.

#### NAME

> posix_openpt - open a pseudo-terminal device

#### SYNOPSIS

> ``[XSI] #include <stdlib.h>
> #include <fcntl.h>
> int posix_openpt(int` oflag`);``
> `
> `

#### DESCRIPTION

> The posix_openpt() function shall establish 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 shall be 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>:

> O_RDWR
>   Open for reading and writing.
> O_NOCTTY
>   If set posix_openpt() shall 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 VALUE

> Upon successful completion, the posix_openpt() function shall open a master pseudo-terminal device and return a non-negative integer representing the lowest numbered unused file descriptor. Otherwise, -1 shall be returned and errno set to indicate the error.

#### ERRORS

> The posix_openpt() function shall 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]
>   Out of pseudo-terminal resources.
> [ENOSR]
>   [XSR] Out of STREAMS resources.

The following sections are informative.

#### EXAMPLES

> ##### Opening a Pseudo-Terminal and Returning the Name of the Slave Device and a 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;

#### APPLICATION USAGE

> This function is a method for portably obtaining a file descriptor of a master terminal device for a pseudo-terminal. The grantpt() and ptsname() functions can be used to manipulate mode and ownership permissions, and to obtain the name of the slave device, respectively.

#### RATIONALE

> The standard developers considered the matter of adding a special device for cloning master pseudo-terminals: the /dev/ptmx device. However, consensus could not be reached, and it was felt that adding a new function would permit other implementations. The posix_openpt() function is designed to complement the grantpt(), ptsname(), and unlockpt() functions.

> On implementations supporting the /dev/ptmx clone device, opening the master device of a pseudo-terminal is simply:

>     mfdp = open("/dev/ptmx", oflag );
>     if (mfdp < 0)
>         return -1;

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> grantpt(), open(), ptsname(), unlockpt(), the Base Definitions volume of IEEE Std 1003.1-2001, <fcntl.h>

#### CHANGE HISTORY

> First released in Issue 6.

End of informative text.

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]