Print this page
14249 pseudo-terminal nomenclature should reflect POSIX
Change-Id: Ib4a3cef899ff4c71b09cb0dc6878863c5e8357bc
@@ -1,126 +1,104 @@
POSIX_OPENPT(3C) Standard C Library Functions POSIX_OPENPT(3C)
NAME
- posix_openpt - open a pseudo terminal device
+ posix_openpt - open a pseudo-terminal manager device
SYNOPSIS
#include <stdlib.h>
#include <fcntl.h>
- int posix_openpt(int oflag);
+ int
+ posix_openpt(int oflag);
-
DESCRIPTION
- The posix_openpt() function establishes a connection between a master
+ 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.
- 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.
- 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() does not cause the terminal device
- to become the controlling terminal for the process.
+ 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
- Upon successful completion, the posix_openpt() function opens a master
- pseudo-terminal device and returns a non-negative integer representing
- the lowest numbered unused file descriptor. Otherwise, -1 is returned
- and errno is set to indicate the error.
+ The posix_getopt() 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.
-ERRORS
- The posix_openpt() function will fail if:
+EXAMPLES
+ Example 1 Open a pseudo-terminal.
- EMFILE
- {OPEN_MAX} file descriptors are currently open in the calling
- process.
+ 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>
- ENFILE
- The maximum allowable number of files is currently open in
- the system.
+ 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");
+ }
- The posix_openpt() function may fail if:
+ printf("subsidiary device is: %s\n", subsidiarydevice);
- EINVAL
- The value of oflag is not valid.
+ if ((subsidiaryfd = open(subsidiary, O_RDWR|O_NOCTTY)) < 0) {
+ err(1, "opening pseudo-terminal subsidiary");
+ }
+ERRORS
+ The posix_openpt() function will fail if:
- EAGAIN
- Out of pseudo-terminal resources.
+ 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.
- ENOSR
- Out of STREAMS resources.
+ The posix_openpt() function may fail if:
+ EINVAL The value of oflag is not valid.
-EXAMPLES
- Example 1 Open a pseudo-terminal.
+ EAGAIN The system has run out of pseudo-terminal resources.
+ ENOSR The system has run out of STREAMS resources.
- The following example opens a pseudo-terminal and returns 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;
-
-
USAGE
- This function provides a method for portably obtaining a file
- descriptor of a master terminal device for a pseudo-terminal. The
- grantpt(3C) and ptsname(3C) functions can be used to manipulate mode
- and ownership permissions and to obtain the name of the slave device,
- respectively.
+ 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(7D) device which is system-specific.
-ATTRIBUTES
- See attributes(5) for descriptions of the following attributes:
+ 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
-
- +--------------------+-----------------+
- | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
- +--------------------+-----------------+
- |Interface Stability | Standard |
- +--------------------+-----------------+
- |MT-Level | MT-Safe |
- +--------------------+-----------------+
-
SEE ALSO
open(2), grantpt(3C), ptsname(3C), unlockpt(3C), attributes(5),
- standards(5)
+ standards(5), ptm(7D), pts(7D)
- June 18, 2021 POSIX_OPENPT(3C)
+illumos February 5, 2022 illumos