Print this page
14249 pseudo-terminal nomenclature should reflect POSIX
Change-Id: Ib4a3cef899ff4c71b09cb0dc6878863c5e8357bc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/posix_openpt.3c.man.txt
+++ new/usr/src/man/man3c/posix_openpt.3c.man.txt
1 1 POSIX_OPENPT(3C) Standard C Library Functions POSIX_OPENPT(3C)
2 2
3 3 NAME
4 - posix_openpt - open a pseudo terminal device
4 + posix_openpt - open a pseudo-terminal manager device
5 5
6 6 SYNOPSIS
7 - #include <stdlib.h>
8 - #include <fcntl.h>
7 + #include <stdlib.h>
8 + #include <fcntl.h>
9 9
10 - int posix_openpt(int oflag);
10 + int
11 + posix_openpt(int oflag);
11 12
12 -
13 13 DESCRIPTION
14 - The posix_openpt() function establishes a connection between a master
15 - device for a pseudo-terminal and a file descriptor. The file descriptor
16 - is used by other I/O functions that refer to that pseudo-terminal.
14 + The posix_openpt() function establishes a connection between a manager
15 + device for a pseudo-terminal and a file descriptor. The file descriptor
16 + is used by other I/O functions that refer to that pseudo-terminal.
17 17
18 + The file status flags and file access modes of the open file description
19 + are set according to the value of oflag.
18 20
19 - The file status flags and file access modes of the open file
20 - description are set according to the value of oflag.
21 + Values for oflag are constructed by a bitwise-inclusive OR of flags from
22 + the following list, defined in fcntl.h(3HEAD):
21 23
24 + O_RDWR Open for reading and writing.
22 25
23 - Values for oflag are constructed by a bitwise-inclusive OR of flags
24 - from the following list, defined in <fcntl.h>.
26 + O_NOCTTY
27 + If set, posix_openpt() does not cause the terminal device to
28 + become the controlling terminal for the process.
25 29
26 - O_RDWR
27 - Open for reading and writing.
30 + The behavior of other values for the oflag argument is unspecified.
28 31
29 -
30 - O_NOCTTY
31 - If set, posix_openpt() does not cause the terminal device
32 - to become the controlling terminal for the process.
33 -
34 -
35 -
36 - The behavior of other values for the oflag argument is unspecified.
37 -
38 32 RETURN VALUES
39 - Upon successful completion, the posix_openpt() function opens a master
40 - pseudo-terminal device and returns a non-negative integer representing
41 - the lowest numbered unused file descriptor. Otherwise, -1 is returned
42 - and errno is set to indicate the error.
33 + The posix_getopt() function opens a manager pseudo-terminal device and,
34 + if successful, returns a non-negative integer representing the lowest
35 + numbered unused file descriptor ; otherwise, the value -1 is returned and
36 + the global variable errno is set to indicate the error.
43 37
44 -ERRORS
45 - The posix_openpt() function will fail if:
38 +EXAMPLES
39 + Example 1 Open a pseudo-terminal.
46 40
47 - EMFILE
48 - {OPEN_MAX} file descriptors are currently open in the calling
49 - process.
41 + The following example opens a pseudo-terminal and returns the name of the
42 + subsidiary device and a file descriptor.
50 43
44 + #include <fcntl.h>
45 + #include <stdio.h>
46 + #include <err.h>
51 47
52 - ENFILE
53 - The maximum allowable number of files is currently open in
54 - the system.
48 + int managerfd, subsidiaryfd;
49 + char *subsidiarydevice;
55 50
51 + if ((managerfd = posix_openpt(O_RDWR|O_NOCTTY)) < 0) {
52 + err(1, "opening pseudo-terminal manager");
53 + }
56 54
55 + if (grantpt(managerfd) != 0 ||
56 + unlockpt(managerfd) != 0 ||
57 + (subsidiarydevice = ptsname(managerfd)) == NULL) {
58 + (void) close(managerfd);
59 + err(1, "locating pseudo-terminal subsidiary");
60 + }
57 61
58 - The posix_openpt() function may fail if:
62 + printf("subsidiary device is: %s\n", subsidiarydevice);
59 63
60 - EINVAL
61 - The value of oflag is not valid.
64 + if ((subsidiaryfd = open(subsidiary, O_RDWR|O_NOCTTY)) < 0) {
65 + err(1, "opening pseudo-terminal subsidiary");
66 + }
62 67
68 +ERRORS
69 + The posix_openpt() function will fail if:
63 70
64 - EAGAIN
65 - Out of pseudo-terminal resources.
71 + EMFILE {OPEN_MAX} file descriptors are currently open in the
72 + calling process.
66 73
74 + ENFILE The maximum allowable number of files is currently
75 + open in the system.
67 76
68 - ENOSR
69 - Out of STREAMS resources.
77 + The posix_openpt() function may fail if:
70 78
79 + EINVAL The value of oflag is not valid.
71 80
72 -EXAMPLES
73 - Example 1 Open a pseudo-terminal.
81 + EAGAIN The system has run out of pseudo-terminal resources.
74 82
83 + ENOSR The system has run out of STREAMS resources.
75 84
76 - The following example opens a pseudo-terminal and returns the name of
77 - the slave device and a file descriptor.
78 -
79 -
80 - #include <fcntl.h>
81 - #include <stdio.h>
82 -
83 - int masterfd, slavefd;
84 - char *slavedevice;
85 -
86 - masterfd = posix_openpt(O_RDWR|O_NOCTTY);
87 -
88 - if (masterfd == -1
89 - || grantpt (masterfd) == -1
90 - || unlockpt (masterfd) == -1
91 - || (slavedevice = ptsname (masterfd)) == NULL)
92 - return -1;
93 -
94 - printf("slave device is: %s\n", slavedevice);
95 -
96 - slavefd = open(slave, O_RDWR|O_NOCTTY);
97 - if (slavefd < 0)
98 - return -1;
99 -
100 -
101 85 USAGE
102 - This function provides a method for portably obtaining a file
103 - descriptor of a master terminal device for a pseudo-terminal. The
104 - grantpt(3C) and ptsname(3C) functions can be used to manipulate mode
105 - and ownership permissions and to obtain the name of the slave device,
106 - respectively.
86 + This function provides a portable method for obtaining the file
87 + descriptor of a manager terminal device for a pseudo-terminal, as opposed
88 + to using open(2) on the ptm(7D) device which is system-specific.
107 89
108 -ATTRIBUTES
109 - See attributes(5) for descriptions of the following attributes:
90 + The grantpt(3C) function can be used to manipulate the mode and ownership
91 + permissions of the subsidiary device. The ptsname(3C) function can be
92 + used to obtain the name of the subsidiary device.
110 93
94 +INTERFACE STABILITY
95 + Committed
111 96
97 +MT LEVEL
98 + MT-Safe
112 99
113 -
114 - +--------------------+-----------------+
115 - | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
116 - +--------------------+-----------------+
117 - |Interface Stability | Standard |
118 - +--------------------+-----------------+
119 - |MT-Level | MT-Safe |
120 - +--------------------+-----------------+
121 -
122 100 SEE ALSO
123 - open(2), grantpt(3C), ptsname(3C), unlockpt(3C), attributes(5),
124 - standards(5)
101 + open(2), grantpt(3C), ptsname(3C), unlockpt(3C), attributes(5),
102 + standards(5), ptm(7D), pts(7D)
125 103
126 - June 18, 2021 POSIX_OPENPT(3C)
104 +illumos February 5, 2022 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX