xref: /openbsd/lib/libutil/openpty.3 (revision c2a62bf3) 
1.\"	$OpenBSD: openpty.3,v 1.18 2017/04/20 17:48:30 nicm 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: April 20 2017 $
34.Dt OPENPTY 3
35.Os
36.Sh NAME
37.Nm openpty ,
38.Nm login_tty ,
39.Nm forkpty
40.Nd tty utility functions
41.Sh SYNOPSIS
42.In termios.h
43.In util.h
44.Ft int
45.Fn getptmfd "void"
46.Ft int
47.Fn openpty "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp"
48.Ft int
49.Fn fdopenpty "int ptmfd" "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp"
50.Ft int
51.Fn login_tty "int fd"
52.Ft pid_t
53.Fn forkpty "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp"
54.Ft pid_t
55.Fn fdforkpty "int ptmfd" "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp"
56.Sh DESCRIPTION
57The
58.Fn openpty ,
59.Fn login_tty ,
60and
61.Fn forkpty
62functions perform manipulations on ttys and pseudo-ttys.
63.Pp
64The
65.Fn openpty
66function finds an available pseudo-tty and returns file descriptors
67for the master and slave in
68.Fa amaster
69and
70.Fa aslave .
71If
72.Fa name
73is non-null, the filename of the slave is returned in
74.Fa name
75(a string of at least 16 characters).
76If
77.Fa termp
78is non-null, the terminal parameters of the slave will be set to the
79values in
80.Fa termp .
81If
82.Fa winp
83is non-null, the window size of the slave will be set to the values in
84.Fa winp .
85.Pp
86The
87.Fn openpty
88function allocates the pseudo-tty through the
89.Pa /dev/ptm
90device (see
91.Xr pty 4
92for details) which means that its ownership is changed to the UID of
93the caller, permissions are set to correct values, and all earlier
94uses of that device are revoked (see
95.Xr revoke 2
96for details).
97.Pp
98The
99.Fn fdopenpty
100and
101.Fn fdforkpty
102functions work like
103.Fn openpty
104and
105.Fn forkpty
106but expect a
107.Pa /dev/ptm
108file descriptor
109.Fa ptmfd
110obtained from the
111.Fn getptmfd
112function.
113.Pp
114The
115.Fn login_tty
116function prepares for a login on the tty
117.Fa fd
118(which may be a real tty device, or the slave of a pseudo-tty as
119returned by
120.Fn openpty )
121by creating a new session, making
122.Fa fd
123the controlling terminal for the current process, setting
124.Fa fd
125to be the standard input, output, and error streams of the current
126process, and closing
127.Fa fd .
128.Pp
129The
130.Fn forkpty
131function combines
132.Fn openpty ,
133.Fn fork ,
134and
135.Fn login_tty
136to create a new process operating in a pseudo-tty.
137The file
138descriptor of the master side of the pseudo-tty is returned in
139.Fa amaster ,
140and the filename of the slave in
141.Fa name
142if it is non-null.
143The
144.Fa termp
145and
146.Fa winp
147parameters, if non-null, will determine the terminal attributes and
148window size of the slave side of the pseudo-tty.
149.Sh RETURN VALUES
150If a call to
151.Fn openpty ,
152.Fn login_tty ,
153or
154.Fn forkpty
155is not successful, \-1 is returned and
156.Va errno
157is set to indicate the error.
158Otherwise,
159.Fn openpty ,
160.Fn login_tty ,
161and the child process of
162.Fn forkpty
163return 0, and the parent process of
164.Fn forkpty
165returns the process ID of the child process.
166.Sh FILES
167.Bl -tag -width /dev/tty[p-zP-T][0-9a-zA-Z]x -compact
168.It Pa /dev/pty[p-zP-T][0-9a-zA-Z]
169master pseudo terminals
170.It Pa /dev/tty[p-zP-T][0-9a-zA-Z]
171slave pseudo terminals
172.It Pa /dev/ptm
173pseudo terminal management device
174.El
175.Sh ERRORS
176.Fn getptmfd
177may fail and set
178.Va errno
179for any of the errors specified for the routine
180.Xr open 2 .
181.Pp
182.Fn openpty
183and
184.Fn fdopenpty
185will fail if:
186.Bl -tag -width Er
187.It Bq Er ENOENT
188There are no available ttys.
189.El
190.Pp
191.Fn fdopenpty
192and
193.Fn fdforkpty
194will fail if
195.Fn getptmfd
196fails.
197.Fn forkpty
198and
199.Fn fdforkpty
200will fail if either
201.Fn openpty
202or
203.Fn fork
204fails.
205.Pp
206.Fn login_tty
207will fail if
208.Fn ioctl
209fails to set
210.Fa fd
211to the controlling terminal of the current process.
212.Sh SEE ALSO
213.Xr fork 2 ,
214.Xr revoke 2 ,
215.Xr pty 4
216