| blob | 68097d0c26cd4d48113d7deca1212a98cd98a0ca |
1 .\" Copyright (c) OpenBSD Group
2 .\" All rights reserved.
3 .\"
4 .\" %%%LICENSE_START(BSD_3_CLAUSE_UCB)
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.
28 .\" %%%LICENSE_END
29 .\"
30 .\" Converted into a manpage again by Martin Schulze <joey@infodrom.org>
31 .\"
32 .\" Added -lutil remark, 030718
33 .\"
34 .TH OPENPTY 3 2021-03-22 "GNU" "Linux Programmer's Manual"
35 .SH NAME
36 openpty, login_tty, forkpty \- terminal utility functions
37 .SH SYNOPSIS
38 .nf
39 .B #include <pty.h>
40 .PP
41 .BI "int openpty(int *" amaster ", int *" aslave ", char *" name ,
42 .BI " const struct termios *" termp ,
43 .BI " const struct winsize *" winp );
44 .BI "pid_t forkpty(int *" amaster ", char *" name ,
45 .BI " const struct termios *" termp ,
46 .BI " const struct winsize *" winp );
47 .PP
48 .B #include <utmp.h>
49 .PP
50 .BI "int login_tty(int " fd );
51 .PP
52 Link with \fI\-lutil\fP.
53 .fi
54 .SH DESCRIPTION
55 The
56 .BR openpty ()
57 function finds an available pseudoterminal and returns file descriptors
58 for the master and slave in
59 .I amaster
60 and
61 .IR aslave .
62 If
63 .I name
64 is not NULL, the filename of the slave is returned in
65 .IR name .
66 If
67 .I termp
68 is not NULL, the terminal parameters of the slave will be set to the
69 values in
70 .IR termp .
71 If
72 .I winp
73 is not NULL, the window size of the slave will be set to the values in
74 .IR winp .
75 .PP
76 The
77 .BR login_tty ()
78 function prepares for a login on the terminal
79 referred to by the file descriptor
80 .I fd
81 (which may be a real terminal device, or the slave of a pseudoterminal as
82 returned by
83 .BR openpty ())
84 by creating a new session, making
85 .I fd
86 the controlling terminal for the calling process, setting
87 .I fd
88 to be the standard input, output, and error streams of the current
89 process, and closing
90 .IR fd .
91 .PP
92 The
93 .BR forkpty ()
94 function combines
95 .BR openpty (),
96 .BR fork (2),
97 and
98 .BR login_tty ()
99 to create a new process operating in a pseudoterminal.
100 A file descriptor referring to
101 master side of the pseudoterminal is returned in
102 .IR amaster .
103 If
104 .I name
105 is not NULL, the buffer it points to is used to return the
106 filename of the slave.
107 The
108 .I termp
109 and
110 .I winp
111 arguments, if not NULL,
112 will determine the terminal attributes and window size of the slave
113 side of the pseudoterminal.
114 .SH RETURN VALUE
115 If a call to
116 .BR openpty (),
117 .BR login_tty (),
118 or
119 .BR forkpty ()
120 is not successful, \-1 is returned and
121 .I errno
122 is set to indicate the error.
123 Otherwise,
124 .BR openpty (),
125 .BR login_tty (),
126 and the child process of
127 .BR forkpty ()
128 return 0, and the parent process of
129 .BR forkpty ()
130 returns the process ID of the child process.
131 .SH ERRORS
132 .BR openpty ()
133 fails if:
134 .TP
135 .B ENOENT
136 There are no available terminals.
137 .PP
138 .BR login_tty ()
139 fails if
140 .BR ioctl (2)
141 fails to set
142 .I fd
143 to the controlling terminal of the calling process.
144 .PP
145 .BR forkpty ()
146 fails if either
147 .BR openpty ()
148 or
149 .BR fork (2)
150 fails.
151 .SH ATTRIBUTES
152 For an explanation of the terms used in this section, see
153 .BR attributes (7).
154 .ad l
155 .nh
156 .TS
157 allbox;
158 lbx lb lb
159 l l l.
160 Interface Attribute Value
161 T{
162 .BR forkpty (),
163 .BR openpty ()
164 T} Thread safety MT-Safe locale
165 T{
166 .BR login_tty ()
167 T} Thread safety MT-Unsafe race:ttyname
168 .TE
169 .hy
170 .ad
171 .sp 1
172 .SH CONFORMING TO
173 These are BSD functions, present in glibc.
174 They are not standardized in POSIX.
175 .SH NOTES
176 The
177 .B const
178 modifiers were added to the structure pointer arguments of
179 .BR openpty ()
180 and
181 .BR forkpty ()
182 in glibc 2.8.
183 .PP
184 In versions of glibc before 2.0.92,
185 .BR openpty ()
186 returns file descriptors for a BSD pseudoterminal pair;
187 since glibc 2.0.92,
188 it first attempts to open a UNIX 98 pseudoterminal pair,
189 and falls back to opening a BSD pseudoterminal pair if that fails.
190 .SH BUGS
191 Nobody knows how much space should be reserved for
192 .IR name .
193 So, calling
194 .BR openpty ()
195 or
196 .BR forkpty ()
197 with non-NULL
198 .I name
199 may not be secure.
200 .SH SEE ALSO
201 .BR fork (2),
202 .BR ttyname (3),
203 .BR pty (7)