Debian Codegraph @

upstream/debian-unstable/man3/openpty.3

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