1 POSIX_OPENPT(3C) Standard C Library Functions POSIX_OPENPT(3C)
2
3 NAME
4 posix_openpt - open a pseudo terminal device
5
6 SYNOPSIS
7 #include <stdlib.h>
8 #include <fcntl.h>
9
10 int posix_openpt(int oflag);
11
12
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.
17
18
19 The file status flags and file access modes of the open file
20 description are set according to the value of oflag.
21
22
23 Values for oflag are constructed by a bitwise-inclusive OR of flags
24 from the following list, defined in <fcntl.h>.
25
26 O_RDWR
27 Open for reading and writing.
28
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 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.
43
44 ERRORS
45 The posix_openpt() function will fail if:
46
47 EMFILE
48 {OPEN_MAX} file descriptors are currently open in the calling
49 process.
50
51
52 ENFILE
53 The maximum allowable number of files is currently open in
54 the system.
55
56
57
58 The posix_openpt() function may fail if:
59
60 EINVAL
61 The value of oflag is not valid.
62
63
64 EAGAIN
65 Out of pseudo-terminal resources.
66
67
68 ENOSR
69 Out of STREAMS resources.
70
71
72 EXAMPLES
73 Example 1 Open a pseudo-terminal.
74
75
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 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.
107
108 ATTRIBUTES
109 See attributes(5) for descriptions of the following attributes:
110
111
112
113
114 +--------------------+-----------------+
115 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
116 +--------------------+-----------------+
117 |Interface Stability | Standard |
118 +--------------------+-----------------+
119 |MT-Level | MT-Safe |
120 +--------------------+-----------------+
121
122 SEE ALSO
123 open(2), grantpt(3C), ptsname(3C), unlockpt(3C), attributes(5),
124 standards(5)
125
126 June 18, 2021 POSIX_OPENPT(3C)
|
1 POSIX_OPENPT(3C) Standard C Library Functions POSIX_OPENPT(3C)
2
3 NAME
4 posix_openpt - open a pseudo-terminal manager device
5
6 SYNOPSIS
7 #include <stdlib.h>
8 #include <fcntl.h>
9
10 int
11 posix_openpt(int oflag);
12
13 DESCRIPTION
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
18 The file status flags and file access modes of the open file description
19 are set according to the value of oflag.
20
21 Values for oflag are constructed by a bitwise-inclusive OR of flags from
22 the following list, defined in fcntl.h(3HEAD):
23
24 O_RDWR Open for reading and writing.
25
26 O_NOCTTY
27 If set, posix_openpt() does not cause the terminal device to
28 become the controlling terminal for the process.
29
30 The behavior of other values for the oflag argument is unspecified.
31
32 RETURN VALUES
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.
37
38 EXAMPLES
39 Example 1 Open a pseudo-terminal.
40
41 The following example opens a pseudo-terminal and returns the name of the
42 subsidiary device and a file descriptor.
43
44 #include <fcntl.h>
45 #include <stdio.h>
46 #include <err.h>
47
48 int managerfd, subsidiaryfd;
49 char *subsidiarydevice;
50
51 if ((managerfd = posix_openpt(O_RDWR|O_NOCTTY)) < 0) {
52 err(1, "opening pseudo-terminal manager");
53 }
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 }
61
62 printf("subsidiary device is: %s\n", subsidiarydevice);
63
64 if ((subsidiaryfd = open(subsidiary, O_RDWR|O_NOCTTY)) < 0) {
65 err(1, "opening pseudo-terminal subsidiary");
66 }
67
68 ERRORS
69 The posix_openpt() function will fail if:
70
71 EMFILE {OPEN_MAX} file descriptors are currently open in the
72 calling process.
73
74 ENFILE The maximum allowable number of files is currently
75 open in the system.
76
77 The posix_openpt() function may fail if:
78
79 EINVAL The value of oflag is not valid.
80
81 EAGAIN The system has run out of pseudo-terminal resources.
82
83 ENOSR The system has run out of STREAMS resources.
84
85 USAGE
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.
89
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.
93
94 INTERFACE STABILITY
95 Committed
96
97 MT LEVEL
98 MT-Safe
99
100 SEE ALSO
101 open(2), grantpt(3C), ptsname(3C), unlockpt(3C), attributes(5),
102 standards(5), ptm(7D), pts(7D)
103
104 illumos February 5, 2022 illumos
|