1.\" $NetBSD: openpty.3,v 1.3 1998/01/09 04:12:21 perry Exp $ 2.\" 3.\" Copyright (c) 1995 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software developed by the Computer Systems 7.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract 8.\" BG 91-66 and contributed to Berkeley. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.Dd November 4, 1996 39.Dt OPENPTY 3 40.Os 41.Sh NAME 42.Nm openpty , 43.Nm login_tty , 44.Nm forkpty 45.Nd tty utility functions 46.Sh SYNOPSIS 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 . 73If 74.Fa termp 75is non-null, the terminal parameters of the slave will be set to the 76values in 77.Fa termp . 78If 79.Fa winp 80is non-null, the window size of the slave will be set to the values in 81.Fa winp . 82.Pp 83The 84.Fn login_tty 85function prepares for a login on the tty 86.Fa fd 87(which may be a real tty device, or the slave of a pseudo-tty as 88returned by 89.Fn openpty ) 90by creating a new session, making 91.Fa fd 92the controlling terminal for the current process, setting 93.Fa fd 94to be the standard input, output, and error streams of the current 95process, and closing 96.Fa fd . 97.Pp 98The 99.Fn forkpty 100function combines 101.Fn openpty , 102.Fn fork , 103and 104.Fn login_tty 105to creates a new process operating in a pseudo-tty. The file 106descriptor of the master side of the pseudo-tty is returned in 107.Fa amaster , 108and the filename of the slave in 109.Fa name 110if it is non-null. The 111.Fa termp 112and 113.Fa winp 114parameters, if non-null, will determine the terminal attributes and 115window size of the slave side of the pseudo-tty. 116.Sh RETURN VALUES 117If a call to 118.Fn openpty , 119.Fn login_tty , 120or 121.Fn forkpty 122is not successful, -1 is returned and 123.Va errno 124is set to indicate the error. Otherwise, 125.Fn openpty , 126.Fn login_tty , 127and the child process of 128.Fn forkpty 129return 0, and the parent process of 130.Fn forkpty 131returns the process ID of the child process. 132.Sh ERRORS 133.Fn openpty 134will fail if: 135.Bl -tag -width Er 136.It Bq Er ENOENT 137There are no available ttys. 138.El 139.Pp 140.Fn login_tty 141will fail if 142.Fn ioctl 143fails to set 144.Fa fd 145to the controlling terminal of the current process. 146.Fn forkpty 147will fail if either 148.Fn openpty 149or 150.Fn fork 151fails. 152.Sh FILES 153.Bl -tag -width /dev/[pt]ty[pqrstuwxyzPQRST][0123456789abcdef] -compact 154.It Pa /dev/[pt]ty[pqrstuwxyzPQRST][0123456789abcdef] 155.El 156.Sh SEE ALSO 157.Xr fork 2 158.Sh BUGS 159The names of the virtual consoles for the i386 PCVT console driver 160conflict with what would be the seventh group of pseudo-ttys, so 161.Fn openpty 162skips 163.Pa /dev/[pt]tyv[0123456789abcdef] 164while looking for pseudo-ttys. 165