jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: openpty.3,v 1.21 2025/06/06 22:01:40 schwarze Exp $
2.\" Copyright (c) 1995
3.\" The Regents of the University of California. All rights reserved.
4.\"
5.\" This code is derived from software developed by the Computer Systems
6.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
7.\" BG 91-66 and contributed to Berkeley.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution.
17.\" 3. Neither the name of the University nor the names of its contributors
18.\" may be used to endorse or promote products derived from this software
19.\" without specific prior written permission.
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31.\" SUCH DAMAGE.
32.\"
33.Dd $Mdocdate: June 6 2025 $
34.Dt OPENPTY 3
35.Os
36.Sh NAME
37.Nm getptmfd ,
38.Nm openpty ,
39.Nm fdopenpty ,
40.Nm login_tty ,
41.Nm forkpty ,
42.Nm fdforkpty
43.Nd tty utility functions
44.Sh SYNOPSIS
45.Lb libutil
46.In termios.h
47.In util.h
48.Ft int
49.Fn getptmfd "void"
50.Ft int
51.Fn openpty "int *amaster" "int *aslave" "char *name" "const struct termios *termp" "const struct winsize *winp"
52.Ft int
53.Fn fdopenpty "int ptmfd" "int *amaster" "int *aslave" "char *name" "const struct termios *termp" "const struct winsize *winp"
54.Ft int
55.Fn login_tty "int fd"
56.Ft pid_t
57.Fn forkpty "int *amaster" "char *name" "const struct termios *termp" "const struct winsize *winp"
58.Ft pid_t
59.Fn fdforkpty "int ptmfd" "int *amaster" "char *name" "const struct termios *termp" "const struct winsize *winp"
60.Sh DESCRIPTION
61The
62.Fn openpty ,
63.Fn login_tty ,
64and
65.Fn forkpty
66functions perform manipulations on ttys and pseudo-ttys.
67.Pp
68The
69.Fn openpty
70function finds an available pseudo-tty and returns file descriptors
71for the master and slave in
72.Fa amaster
73and
74.Fa aslave .
75If
76.Fa name
77is non-null, the filename of the slave is returned in
78.Fa name
79(a string of at least 16 characters).
80If
81.Fa termp
82is non-null, the terminal parameters of the slave will be set to the
83values in
84.Fa termp .
85If
86.Fa winp
87is non-null, the window size of the slave will be set to the values in
88.Fa winp .
89.Pp
90The
91.Fn openpty
92function allocates the pseudo-tty through the
93.Pa /dev/ptm
94device (see
95.Xr pty 4
96for details) which means that its ownership is changed to the UID of
97the caller, permissions are set to correct values, and all earlier
98uses of that device are revoked (see
99.Xr revoke 2
100for details).
101.Pp
102The
103.Fn fdopenpty
104and
105.Fn fdforkpty
106functions work like
107.Fn openpty
108and
109.Fn forkpty
110but expect a
111.Pa /dev/ptm
112file descriptor
113.Fa ptmfd
114obtained from the
115.Fn getptmfd
116function.
117.Pp
118The
119.Fn login_tty
120function prepares for a login on the tty
121.Fa fd
122(which may be a real tty device, or the slave of a pseudo-tty as
123returned by
124.Fn openpty )
125by creating a new session, making
126.Fa fd
127the controlling terminal for the current process, setting
128.Fa fd
129to be the standard input, output, and error streams of the current
130process, and closing
131.Fa fd .
132.Pp
133The
134.Fn forkpty
135function combines
136.Fn openpty ,
137.Fn fork ,
138and
139.Fn login_tty
140to create a new process operating in a pseudo-tty.
141The file
142descriptor of the master side of the pseudo-tty is returned in
143.Fa amaster ,
144and the filename of the slave in
145.Fa name
146if it is non-null.
147The
148.Fa termp
149and
150.Fa winp
151parameters, if non-null, will determine the terminal attributes and
152window size of the slave side of the pseudo-tty.
153.Sh RETURN VALUES
154If a call to
155.Fn openpty ,
156.Fn login_tty ,
157or
158.Fn forkpty
159is not successful, \-1 is returned and
160.Va errno
161is set to indicate the error.
162Otherwise,
163.Fn openpty ,
164.Fn login_tty ,
165and the child process of
166.Fn forkpty
167return 0, and the parent process of
168.Fn forkpty
169returns the process ID of the child process.
170.Sh FILES
171.Bl -tag -width /dev/tty[p-zP-T][0-9a-zA-Z]x -compact
172.It Pa /dev/pty[p-zP-T][0-9a-zA-Z]
173master pseudo terminals
174.It Pa /dev/tty[p-zP-T][0-9a-zA-Z]
175slave pseudo terminals
176.It Pa /dev/ptm
177pseudo terminal management device
178.El
179.Sh ERRORS
180.Fn getptmfd
181may fail and set
182.Va errno
183for any of the errors specified for the routine
184.Xr open 2 .
185.Pp
186.Fn openpty
187and
188.Fn fdopenpty
189will fail if:
190.Bl -tag -width Er
191.It Bq Er ENOENT
192There are no available ttys.
193.El
194.Pp
195.Fn fdopenpty
196and
197.Fn fdforkpty
198will fail if
199.Fn getptmfd
200fails.
201.Fn forkpty
202and
203.Fn fdforkpty
204will fail if either
205.Fn openpty
206or
207.Fn fork
208fails.
209.Pp
210.Fn login_tty
211will fail if
212.Fn ioctl
213fails to set
214.Fa fd
215to the controlling terminal of the current process.
216.Sh SEE ALSO
217.Xr fork 2 ,
218.Xr revoke 2 ,
219.Xr pty 4