The Open Group Base Specifications Issue 7
IEEE Std 1003.1, 2013 Edition
Copyright © 2001-2013 The IEEE and The Open Group

#### 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]
>   All file descriptors available to the process are currently open.
> [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]
>   [OB 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(slavedevice, 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

> XBD <fcntl.h>, <stdlib.h>

#### CHANGE HISTORY

> First released in Issue 6.

#### Issue 7

> SD5-XBD-ERN-4 is applied, changing the definition of the [EMFILE] error.

> SD5-XSH-ERN-51 is applied, correcting an error in the EXAMPLES section.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2013 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]