Print this page
14249 pseudo-terminal nomenclature should reflect POSIX
Change-Id: Ib4a3cef899ff4c71b09cb0dc6878863c5e8357bc
*** 1,126 ****
POSIX_OPENPT(3C) Standard C Library Functions POSIX_OPENPT(3C)
NAME
! posix_openpt - open a pseudo terminal device
SYNOPSIS
#include <stdlib.h>
#include <fcntl.h>
! int posix_openpt(int oflag);
-
DESCRIPTION
! The posix_openpt() function 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 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() 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.
! ERRORS
! The posix_openpt() function 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() function may fail if:
! EINVAL
! The value of oflag is not valid.
! EAGAIN
! Out of pseudo-terminal resources.
! ENOSR
! Out of STREAMS resources.
! EXAMPLES
! Example 1 Open a pseudo-terminal.
- 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.
! ATTRIBUTES
! See attributes(5) for descriptions of the following attributes:
-
- +--------------------+-----------------+
- | 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)
! June 18, 2021 POSIX_OPENPT(3C)
--- 1,104 ----
POSIX_OPENPT(3C) Standard C Library Functions POSIX_OPENPT(3C)
NAME
! posix_openpt - open a pseudo-terminal manager device
SYNOPSIS
#include <stdlib.h>
#include <fcntl.h>
! int
! posix_openpt(int oflag);
DESCRIPTION
! 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.
! 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.
O_NOCTTY
! 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
! 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.
! EXAMPLES
! Example 1 Open a pseudo-terminal.
! 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>
! 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");
+ }
! printf("subsidiary device is: %s\n", subsidiarydevice);
! if ((subsidiaryfd = open(subsidiary, O_RDWR|O_NOCTTY)) < 0) {
! err(1, "opening pseudo-terminal subsidiary");
! }
+ ERRORS
+ The posix_openpt() function 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() function may fail if:
+ EINVAL The value of oflag is not valid.
! EAGAIN The system has run out of pseudo-terminal resources.
+ ENOSR The system has run out of STREAMS resources.
USAGE
! 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.
! 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
SEE ALSO
open(2), grantpt(3C), ptsname(3C), unlockpt(3C), attributes(5),
! standards(5), ptm(7D), pts(7D)
! illumos February 5, 2022 illumos