]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) OpenBSD Group |
2 | .\" All rights reserved. | |
3 | .\" | |
491b7776 | 4 | .\" %%%LICENSE_START(BSD_3_CLAUSE_UCB) |
fea681da MK |
5 | .\" Redistribution and use in source and binary forms, with or without |
6 | .\" modification, are permitted provided that the following conditions | |
7 | .\" are met: | |
8 | .\" 1. Redistributions of source code must retain the above copyright | |
9 | .\" notice, this list of conditions and the following disclaimer. | |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer in the | |
12 | .\" documentation and/or other materials provided with the distribution. | |
13 | .\" 3. Neither the name of the University nor the names of its contributors | |
14 | .\" may be used to endorse or promote products derived from this software | |
15 | .\" without specific prior written permission. | |
16 | .\" | |
17 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
18 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
19 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
20 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
21 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
22 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
23 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
24 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
25 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
26 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
27 | .\" SUCH DAMAGE. | |
8c9302dc | 28 | .\" %%%LICENSE_END |
fea681da MK |
29 | .\" |
30 | .\" Converted into a manpage again by Martin Schulze <joey@infodrom.org> | |
31 | .\" | |
32 | .\" Added -lutil remark, 030718 | |
33 | .\" | |
4b8c67d9 | 34 | .TH OPENPTY 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da | 35 | .SH NAME |
1285ff3d | 36 | openpty, login_tty, forkpty \- terminal utility functions |
fea681da | 37 | .SH SYNOPSIS |
b9f02710 | 38 | .nf |
fea681da | 39 | .B #include <pty.h> |
68e4db0a | 40 | .PP |
c13182ef | 41 | .BI "int openpty(int *" amaster ", int *" aslave ", char *" name , |
671c2ab4 EB |
42 | .BI " const struct termios *" termp , |
43 | .BI " const struct winsize *" winp ); | |
68e4db0a | 44 | .PP |
671c2ab4 EB |
45 | .BI "pid_t forkpty(int *" amaster ", char *" name , |
46 | .BI " const struct termios *" termp , | |
47 | .BI " const struct winsize *" winp ); | |
f90f031e | 48 | |
cbaed691 | 49 | .B #include <utmp.h> |
68e4db0a | 50 | .PP |
cbaed691 | 51 | .BI "int login_tty(int " fd ); |
68e4db0a | 52 | .PP |
7c2bff69 | 53 | Link with \fI\-lutil\fP. |
b9f02710 | 54 | .fi |
fea681da MK |
55 | .SH DESCRIPTION |
56 | The | |
63aa9df0 | 57 | .BR openpty () |
b218b023 | 58 | function finds an available pseudoterminal and returns file descriptors |
fea681da MK |
59 | for the master and slave in |
60 | .I amaster | |
61 | and | |
62 | .IR aslave . | |
63 | If | |
64 | .I name | |
65 | is not NULL, the filename of the slave is returned in | |
66 | .IR name . | |
67 | If | |
68 | .I termp | |
69 | is not NULL, the terminal parameters of the slave will be set to the | |
70 | values in | |
71 | .IR termp . | |
72 | If | |
73 | .I winp | |
74 | is not NULL, the window size of the slave will be set to the values in | |
75 | .IR winp . | |
847e0d88 | 76 | .PP |
fea681da | 77 | The |
63aa9df0 | 78 | .BR login_tty () |
1285ff3d | 79 | function prepares for a login on the terminal |
fea681da | 80 | .I fd |
1285ff3d | 81 | (which may be a real terminal device, or the slave of a pseudoterminal as |
fea681da | 82 | returned by |
63aa9df0 | 83 | .BR openpty ()) |
fea681da MK |
84 | by creating a new session, making |
85 | .I fd | |
a1ffe9f5 | 86 | the controlling terminal for the calling process, setting |
fea681da MK |
87 | .I fd |
88 | to be the standard input, output, and error streams of the current | |
89 | process, and closing | |
90 | .IR fd . | |
847e0d88 | 91 | .PP |
fea681da | 92 | The |
63aa9df0 | 93 | .BR forkpty () |
fea681da | 94 | function combines |
63aa9df0 | 95 | .BR openpty (), |
fb186734 | 96 | .BR fork (2), |
fea681da | 97 | and |
63aa9df0 | 98 | .BR login_tty () |
b218b023 | 99 | to create a new process operating in a pseudoterminal. |
c13182ef | 100 | The file |
b218b023 | 101 | descriptor of the master side of the pseudoterminal is returned in |
69060c5f MK |
102 | .IR amaster . |
103 | If | |
fea681da | 104 | .I name |
69060c5f | 105 | is not NULL, the buffer it points to is used to return the |
13e69b6c | 106 | filename of the slave. |
c13182ef | 107 | The |
fea681da MK |
108 | .I termp |
109 | and | |
110 | .I winp | |
c4bb193f | 111 | arguments, if not NULL, |
fea681da | 112 | will determine the terminal attributes and window size of the slave |
b218b023 | 113 | side of the pseudoterminal. |
47297adb | 114 | .SH RETURN VALUE |
fea681da | 115 | If a call to |
63aa9df0 MK |
116 | .BR openpty (), |
117 | .BR login_tty (), | |
fea681da | 118 | or |
63aa9df0 | 119 | .BR forkpty () |
8729177b | 120 | is not successful, \-1 is returned and |
fea681da | 121 | .I errno |
c13182ef MK |
122 | is set to indicate the error. |
123 | Otherwise, | |
63aa9df0 MK |
124 | .BR openpty (), |
125 | .BR login_tty (), | |
fea681da | 126 | and the child process of |
63aa9df0 | 127 | .BR forkpty () |
fea681da | 128 | return 0, and the parent process of |
63aa9df0 | 129 | .BR forkpty () |
fea681da MK |
130 | returns the process ID of the child process. |
131 | .SH ERRORS | |
63aa9df0 | 132 | .BR openpty () |
26cd31fd | 133 | fails if: |
fea681da MK |
134 | .TP |
135 | .B ENOENT | |
1285ff3d | 136 | There are no available terminals. |
dd3568a1 | 137 | .PP |
2a1b7cdc | 138 | .BR login_tty () |
26cd31fd | 139 | fails if |
fb186734 | 140 | .BR ioctl (2) |
fea681da MK |
141 | fails to set |
142 | .I fd | |
a1ffe9f5 | 143 | to the controlling terminal of the calling process. |
dd3568a1 | 144 | .PP |
63aa9df0 | 145 | .BR forkpty () |
26cd31fd | 146 | fails if either |
63aa9df0 | 147 | .BR openpty () |
fea681da | 148 | or |
fb186734 | 149 | .BR fork (2) |
fea681da | 150 | fails. |
a46e97ad ZL |
151 | .SH ATTRIBUTES |
152 | For an explanation of the terms used in this section, see | |
153 | .BR attributes (7). | |
154 | .TS | |
155 | allbox; | |
156 | lbw20 lb lb | |
157 | l l l. | |
158 | Interface Attribute Value | |
159 | T{ | |
160 | .BR forkpty (), | |
161 | .BR openpty () | |
162 | T} Thread safety MT-Safe locale | |
163 | T{ | |
164 | .BR login_tty () | |
165 | T} Thread safety MT-Unsafe race:ttyname | |
166 | .TE | |
847e0d88 | 167 | .sp 1 |
47297adb | 168 | .SH CONFORMING TO |
b86c469a | 169 | These are BSD functions, present in glibc. |
8b3f5f59 | 170 | They are not standardized in POSIX. |
660dd25f | 171 | .SH NOTES |
49c32f8f MK |
172 | The |
173 | .B const | |
174 | modifiers were added to the structure pointer arguments of | |
175 | .BR openpty () | |
176 | and | |
177 | .BR forkpty () | |
178 | in glibc 2.8. | |
847e0d88 | 179 | .PP |
660dd25f MK |
180 | In versions of glibc before 2.0.92, |
181 | .BR openpty () | |
b218b023 | 182 | returns file descriptors for a BSD pseudoterminal pair; |
c13182ef | 183 | since glibc 2.0.92, |
b218b023 MK |
184 | it first attempts to open a UNIX 98 pseudoterminal pair, |
185 | and falls back to opening a BSD pseudoterminal pair if that fails. | |
fea681da MK |
186 | .SH BUGS |
187 | Nobody knows how much space should be reserved for | |
188 | .IR name . | |
189 | So, calling | |
63aa9df0 | 190 | .BR openpty () |
fea681da | 191 | or |
63aa9df0 | 192 | .BR forkpty () |
fea681da MK |
193 | with non-NULL |
194 | .I name | |
195 | may not be secure. | |
47297adb | 196 | .SH SEE ALSO |
88ab292b | 197 | .BR fork (2), |
4d31e3ea | 198 | .BR ttyname (3), |
88ab292b | 199 | .BR pty (7) |