posix_openpt — open a pseudo-terminal device
The posix_openpt() function shall establish a connection between a manager device for a pseudo-terminal and a file descriptor. The file descriptor shall be allocated as described in 2.6 File Descriptor Allocation and can be 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:
- O_RDWR
- Open for reading and writing.
- O_CLOEXEC
- Atomically set the FD_CLOEXEC flag on the file descriptor.
- O_CLOFORK
- Atomically set the FD_CLOFORK flag on the file descriptor.
- 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.
Upon successful completion, the posix_openpt() function shall open a file descriptor for a manager pseudo-terminal device and return a non-negative integer representing the file descriptor. Otherwise, -1 shall be returned and errno set to indicate the error.
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.
Opening a Pseudo-Terminal and Returning the Name of the Subsidiary Device and a File Descriptor
#include <fcntl.h> #include <stdio.h> #include <stdlib.h>
int managerfd, subsidiaryfd; char *subsidiarydevice;
managerfd = posix_openpt(O_RDWR|O_NOCTTY);
if (managerfd == -1 || grantpt (managerfd) == -1 || unlockpt (managerfd) == -1 || (subsidiarydevice = ptsname (managerfd)) == NULL) return -1;
printf("subsidiary device is: %s\n", subsidiarydevice);
subsidiaryfd = open(subsidiarydevice, O_RDWR|O_NOCTTY); if (subsidiaryfd < 0) return -1;
This function is a method for portably obtaining a file descriptor of a manager terminal device for a pseudo-terminal. The grantpt() function and the ptsname() and ptsname_r() functions can be used to manipulate mode and ownership permissions, and to obtain the name of the subsidiary device, respectively.
The standard developers considered the matter of adding a special device for cloning manager pseudo-terminal devices: 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(), ptsname_r(), and unlockpt() functions.
On implementations supporting the /dev/ptmx clone device, opening the manager device of a pseudo-terminal is simply:
mfdp = open("/dev/ptmx", oflag ); if (mfdp < 0) return -1;The O_CLOEXEC and O_CLOFORK flags are necessary to avoid a data race in multi-threaded applications. Without O_CLOFORK, a file descriptor is leaked into a child process created by one thread in the window between another thread creating a file descriptor with posix_openpt() and then using fcntl() to set the FD_CLOFORK flag. Without O_CLOEXEC, a file descriptor intentionally inherited by child processes is similarly leaked into an executed program if FD_CLOEXEC is not set atomically.
None.
2.6 File Descriptor Allocation , grantpt , open , ptsname , unlockpt
XBD <fcntl.h> , <stdlib.h>
First released in Issue 6.
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.
POSIX.1-2008, Technical Corrigendum 2, XSH/TC2-2008/0253 [835] and XSH/TC2-2008/0254 [835] are applied.
Austin Group Defects 411 and 1318 are applied, adding O_CLOEXEC and O_CLOFORK.
Austin Group Defect 508 is applied, changing the APPLICATION USAGE and RATIONALE sections to refer to ptsname_r() as well as ptsname().
Austin Group Defect 593 is applied, removing #include <fcntl.h> from the SYNOPSIS and a reference to <fcntl.h> from the DESCRIPTION section.
Austin Group Defect 1330 is applied, removing obsolescent interfaces.
Austin Group Defect 1466 is applied, changing the terminology used for pseudo-terminal devices.
return to top of page