]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da MK |
2 | .\" Copyright (c) OpenBSD Group |
3 | .\" All rights reserved. | |
4 | .\" | |
40fa0ff4 | 5 | .\" SPDX-License-Identifier: BSD-3-Clause |
fea681da MK |
6 | .\" |
7 | .\" Converted into a manpage again by Martin Schulze <joey@infodrom.org> | |
8 | .\" | |
9 | .\" Added -lutil remark, 030718 | |
10 | .\" | |
4c1c5274 | 11 | .TH openpty 3 (date) "Linux man-pages (unreleased)" |
fea681da | 12 | .SH NAME |
1285ff3d | 13 | openpty, login_tty, forkpty \- terminal utility functions |
61ca7cb0 AC |
14 | .SH LIBRARY |
15 | System utilities library | |
8fc3b2cf | 16 | .RI ( libutil ", " \-lutil ) |
fea681da | 17 | .SH SYNOPSIS |
b9f02710 | 18 | .nf |
fea681da | 19 | .B #include <pty.h> |
c6d039a3 | 20 | .P |
c13182ef | 21 | .BI "int openpty(int *" amaster ", int *" aslave ", char *" name , |
f2667a72 MK |
22 | .BI " const struct termios *" termp , |
23 | .BI " const struct winsize *" winp ); | |
671c2ab4 EB |
24 | .BI "pid_t forkpty(int *" amaster ", char *" name , |
25 | .BI " const struct termios *" termp , | |
26 | .BI " const struct winsize *" winp ); | |
c6d039a3 | 27 | .P |
cbaed691 | 28 | .B #include <utmp.h> |
c6d039a3 | 29 | .P |
cbaed691 | 30 | .BI "int login_tty(int " fd ); |
b9f02710 | 31 | .fi |
fea681da MK |
32 | .SH DESCRIPTION |
33 | The | |
63aa9df0 | 34 | .BR openpty () |
b218b023 | 35 | function finds an available pseudoterminal and returns file descriptors |
fea681da MK |
36 | for the master and slave in |
37 | .I amaster | |
38 | and | |
39 | .IR aslave . | |
40 | If | |
41 | .I name | |
42 | is not NULL, the filename of the slave is returned in | |
43 | .IR name . | |
44 | If | |
45 | .I termp | |
46 | is not NULL, the terminal parameters of the slave will be set to the | |
47 | values in | |
48 | .IR termp . | |
49 | If | |
50 | .I winp | |
51 | is not NULL, the window size of the slave will be set to the values in | |
52 | .IR winp . | |
c6d039a3 | 53 | .P |
fea681da | 54 | The |
63aa9df0 | 55 | .BR login_tty () |
1285ff3d | 56 | function prepares for a login on the terminal |
980a2628 | 57 | referred to by the file descriptor |
fea681da | 58 | .I fd |
1285ff3d | 59 | (which may be a real terminal device, or the slave of a pseudoterminal as |
fea681da | 60 | returned by |
63aa9df0 | 61 | .BR openpty ()) |
fea681da MK |
62 | by creating a new session, making |
63 | .I fd | |
a1ffe9f5 | 64 | the controlling terminal for the calling process, setting |
fea681da MK |
65 | .I fd |
66 | to be the standard input, output, and error streams of the current | |
67 | process, and closing | |
68 | .IR fd . | |
c6d039a3 | 69 | .P |
fea681da | 70 | The |
63aa9df0 | 71 | .BR forkpty () |
fea681da | 72 | function combines |
63aa9df0 | 73 | .BR openpty (), |
fb186734 | 74 | .BR fork (2), |
fea681da | 75 | and |
63aa9df0 | 76 | .BR login_tty () |
b218b023 | 77 | to create a new process operating in a pseudoterminal. |
980a2628 MK |
78 | A file descriptor referring to |
79 | master side of the pseudoterminal is returned in | |
69060c5f MK |
80 | .IR amaster . |
81 | If | |
fea681da | 82 | .I name |
69060c5f | 83 | is not NULL, the buffer it points to is used to return the |
13e69b6c | 84 | filename of the slave. |
c13182ef | 85 | The |
fea681da MK |
86 | .I termp |
87 | and | |
88 | .I winp | |
c4bb193f | 89 | arguments, if not NULL, |
fea681da | 90 | will determine the terminal attributes and window size of the slave |
b218b023 | 91 | side of the pseudoterminal. |
47297adb | 92 | .SH RETURN VALUE |
fea681da | 93 | If a call to |
63aa9df0 MK |
94 | .BR openpty (), |
95 | .BR login_tty (), | |
fea681da | 96 | or |
63aa9df0 | 97 | .BR forkpty () |
8729177b | 98 | is not successful, \-1 is returned and |
fea681da | 99 | .I errno |
c13182ef MK |
100 | is set to indicate the error. |
101 | Otherwise, | |
63aa9df0 MK |
102 | .BR openpty (), |
103 | .BR login_tty (), | |
fea681da | 104 | and the child process of |
63aa9df0 | 105 | .BR forkpty () |
fea681da | 106 | return 0, and the parent process of |
63aa9df0 | 107 | .BR forkpty () |
fea681da MK |
108 | returns the process ID of the child process. |
109 | .SH ERRORS | |
63aa9df0 | 110 | .BR openpty () |
26cd31fd | 111 | fails if: |
fea681da MK |
112 | .TP |
113 | .B ENOENT | |
1285ff3d | 114 | There are no available terminals. |
c6d039a3 | 115 | .P |
2a1b7cdc | 116 | .BR login_tty () |
26cd31fd | 117 | fails if |
fb186734 | 118 | .BR ioctl (2) |
fea681da MK |
119 | fails to set |
120 | .I fd | |
a1ffe9f5 | 121 | to the controlling terminal of the calling process. |
c6d039a3 | 122 | .P |
63aa9df0 | 123 | .BR forkpty () |
26cd31fd | 124 | fails if either |
63aa9df0 | 125 | .BR openpty () |
fea681da | 126 | or |
fb186734 | 127 | .BR fork (2) |
fea681da | 128 | fails. |
a46e97ad ZL |
129 | .SH ATTRIBUTES |
130 | For an explanation of the terms used in this section, see | |
131 | .BR attributes (7). | |
132 | .TS | |
133 | allbox; | |
c466875e | 134 | lbx lb lb |
a46e97ad ZL |
135 | l l l. |
136 | Interface Attribute Value | |
137 | T{ | |
9e54434e BR |
138 | .na |
139 | .nh | |
a46e97ad ZL |
140 | .BR forkpty (), |
141 | .BR openpty () | |
142 | T} Thread safety MT-Safe locale | |
143 | T{ | |
9e54434e BR |
144 | .na |
145 | .nh | |
a46e97ad ZL |
146 | .BR login_tty () |
147 | T} Thread safety MT-Unsafe race:ttyname | |
148 | .TE | |
3113c7f3 | 149 | .SH STANDARDS |
4131356c AC |
150 | BSD. |
151 | .SH HISTORY | |
49c32f8f MK |
152 | The |
153 | .B const | |
154 | modifiers were added to the structure pointer arguments of | |
155 | .BR openpty () | |
156 | and | |
157 | .BR forkpty () | |
158 | in glibc 2.8. | |
c6d039a3 | 159 | .P |
b324e17d | 160 | Before glibc 2.0.92, |
660dd25f | 161 | .BR openpty () |
b218b023 | 162 | returns file descriptors for a BSD pseudoterminal pair; |
c13182ef | 163 | since glibc 2.0.92, |
b218b023 MK |
164 | it first attempts to open a UNIX 98 pseudoterminal pair, |
165 | and falls back to opening a BSD pseudoterminal pair if that fails. | |
fea681da MK |
166 | .SH BUGS |
167 | Nobody knows how much space should be reserved for | |
168 | .IR name . | |
169 | So, calling | |
63aa9df0 | 170 | .BR openpty () |
fea681da | 171 | or |
63aa9df0 | 172 | .BR forkpty () |
fea681da MK |
173 | with non-NULL |
174 | .I name | |
175 | may not be secure. | |
47297adb | 176 | .SH SEE ALSO |
88ab292b | 177 | .BR fork (2), |
4d31e3ea | 178 | .BR ttyname (3), |
88ab292b | 179 | .BR pty (7) |