1.\" $OpenBSD: openpty.3,v 1.7 2001/07/13 22:14:07 millert 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. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the University of 20.\" California, Berkeley and its contributors. 21.\" 4. Neither the name of the University nor the names of its contributors 22.\" may be used to endorse or promote products derived from this software 23.\" without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 26.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 29.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35.\" SUCH DAMAGE. 36.\" 37.Dd November 4, 1996 38.Dt OPENPTY 3 39.Os 40.Sh NAME 41.Nm openpty , 42.Nm login_tty , 43.Nm forkpty 44.Nd tty utility functions 45.Sh SYNOPSIS 46.Fd #include <termios.h> 47.Fd #include <util.h> 48.Ft int 49.Fn openpty "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.Sh DESCRIPTION 55The 56.Fn openpty , 57.Fn login_tty , 58and 59.Fn forkpty 60functions perform manipulations on ttys and pseudo-ttys. 61.Pp 62The 63.Fn openpty 64function finds an available pseudo-tty and returns file descriptors 65for the master and slave in 66.Fa amaster 67and 68.Fa aslave . 69If 70.Fa name 71is non-null, the filename of the slave is returned in 72.Fa name 73(a string of at least 16 characters). 74If 75.Fa termp 76is non-null, the terminal parameters of the slave will be set to the 77values in 78.Fa termp . 79If 80.Fa winp 81is non-null, the window size of the slave will be set to the values in 82.Fa winp . 83.Pp 84The 85.Fn login_tty 86function prepares for a login on the tty 87.Fa fd 88(which may be a real tty device, or the slave of a pseudo-tty as 89returned by 90.Fn openpty ) 91by creating a new session, making 92.Fa fd 93the controlling terminal for the current process, setting 94.Fa fd 95to be the standard input, output, and error streams of the current 96process, and closing 97.Fa fd . 98.Pp 99The 100.Fn forkpty 101function combines 102.Fn openpty , 103.Fn fork , 104and 105.Fn login_tty 106to creates a new process operating in a pseudo-tty. The file 107descriptor of the master side of the pseudo-tty is returned in 108.Fa amaster , 109and the filename of the slave in 110.Fa name 111if it is non-null. The 112.Fa termp 113and 114.Fa winp 115parameters, if non-null, will determine the terminal attributes and 116window size of the slave side of the pseudo-tty. 117.Sh RETURN VALUES 118If a call to 119.Fn openpty , 120.Fn login_tty , 121or 122.Fn forkpty 123is not successful, \-1 is returned and 124.Va errno 125is set to indicate the error. Otherwise, 126.Fn openpty , 127.Fn login_tty , 128and the child process of 129.Fn forkpty 130return 0, and the parent process of 131.Fn forkpty 132returns the process ID of the child process. 133.Sh ERRORS 134.Fn openpty 135will fail if: 136.Bl -tag -width Er 137.It Bq Er ENOENT 138There are no available ttys. 139.El 140.Pp 141.Fn login_tty 142will fail if 143.Fn ioctl 144fails to set 145.Fa fd 146to the controlling terminal of the current process. 147.Fn forkpty 148will fail if either 149.Fn openpty 150or 151.Fn fork 152fails. 153.Sh FILES 154.Bl -tag -width /dev/[pt]ty[pqrstuvwxyzPQRST][0123456789abcdef] -compact 155.It Pa /dev/[pt]ty[pqrstuvwxyzPQRST][0123456789abcdef] 156.El 157.Sh SEE ALSO 158.Xr fork 2 159