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