Debian Codegraph @

upstream/debian-trixie/man3/openpty.3

raw
1 '\" t
2 .\" Copyright (c) OpenBSD Group
3 .\" All rights reserved.
4 .\"
5 .\" SPDX-License-Identifier: BSD-3-Clause
6 .\"
7 .\" Converted into a manpage again by Martin Schulze <[email protected]>
8 .\"
9 .\" Added -lutil remark, 030718
10 .\"
11 .TH openpty 3 2024-05-02 "Linux man-pages 6.9.1"
12 .SH NAME
13 openpty, login_tty, forkpty \- terminal utility functions
14 .SH LIBRARY
15 System utilities library
16 .RI ( libutil ", " \-lutil )
17 .SH SYNOPSIS
18 .nf
19 .B #include <pty.h>
20 .P
21 .BI "int openpty(int *" amaster ", int *" aslave ", char *" name ,
22 .BI " const struct termios *" termp ,
23 .BI " const struct winsize *" winp );
24 .BI "pid_t forkpty(int *" amaster ", char *" name ,
25 .BI " const struct termios *" termp ,
26 .BI " const struct winsize *" winp );
27 .P
28 .B #include <utmp.h>
29 .P
30 .BI "int login_tty(int " fd );
31 .fi
32 .SH DESCRIPTION
33 The
34 .BR openpty ()
35 function finds an available pseudoterminal and returns file descriptors
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 .
53 .P
54 The
55 .BR login_tty ()
56 function prepares for a login on the terminal
57 referred to by the file descriptor
58 .I fd
59 (which may be a real terminal device, or the slave of a pseudoterminal as
60 returned by
61 .BR openpty ())
62 by creating a new session, making
63 .I fd
64 the controlling terminal for the calling process, setting
65 .I fd
66 to be the standard input, output, and error streams of the current
67 process, and closing
68 .IR fd .
69 .P
70 The
71 .BR forkpty ()
72 function combines
73 .BR openpty (),
74 .BR fork (2),
75 and
76 .BR login_tty ()
77 to create a new process operating in a pseudoterminal.
78 A file descriptor referring to
79 master side of the pseudoterminal is returned in
80 .IR amaster .
81 If
82 .I name
83 is not NULL, the buffer it points to is used to return the
84 filename of the slave.
85 The
86 .I termp
87 and
88 .I winp
89 arguments, if not NULL,
90 will determine the terminal attributes and window size of the slave
91 side of the pseudoterminal.
92 .SH RETURN VALUE
93 If a call to
94 .BR openpty (),
95 .BR login_tty (),
96 or
97 .BR forkpty ()
98 is not successful, \-1 is returned and
99 .I errno
100 is set to indicate the error.
101 Otherwise,
102 .BR openpty (),
103 .BR login_tty (),
104 and the child process of
105 .BR forkpty ()
106 return 0, and the parent process of
107 .BR forkpty ()
108 returns the process ID of the child process.
109 .SH ERRORS
110 .BR openpty ()
111 fails if:
112 .TP
113 .B ENOENT
114 There are no available terminals.
115 .P
116 .BR login_tty ()
117 fails if
118 .BR ioctl (2)
119 fails to set
120 .I fd
121 to the controlling terminal of the calling process.
122 .P
123 .BR forkpty ()
124 fails if either
125 .BR openpty ()
126 or
127 .BR fork (2)
128 fails.
129 .SH ATTRIBUTES
130 For an explanation of the terms used in this section, see
131 .BR attributes (7).
132 .TS
133 allbox;
134 lbx lb lb
135 l l l.
136 Interface Attribute Value
137 T{
138 .na
139 .nh
140 .BR forkpty (),
141 .BR openpty ()
142 T} Thread safety MT-Safe locale
143 T{
144 .na
145 .nh
146 .BR login_tty ()
147 T} Thread safety MT-Unsafe race:ttyname
148 .TE
149 .SH STANDARDS
150 BSD.
151 .SH HISTORY
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.
159 .P
160 Before glibc 2.0.92,
161 .BR openpty ()
162 returns file descriptors for a BSD pseudoterminal pair;
163 since glibc 2.0.92,
164 it first attempts to open a UNIX 98 pseudoterminal pair,
165 and falls back to opening a BSD pseudoterminal pair if that fails.
166 .SH BUGS
167 Nobody knows how much space should be reserved for
168 .IR name .
169 So, calling
170 .BR openpty ()
171 or
172 .BR forkpty ()
173 with non-NULL
174 .I name
175 may not be secure.
176 .SH SEE ALSO
177 .BR fork (2),
178 .BR ttyname (3),
179 .BR pty (7)