1.\" $NetBSD: openpty.3,v 1.17 2012/07/27 21:33:46 christos 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. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd July 27, 2012 35.Dt OPENPTY 3 36.Os 37.Sh NAME 38.Nm openpty , 39.Nm login_tty , 40.Nm forkpty 41.Nd tty utility functions 42.Sh LIBRARY 43.Lb libutil 44.Sh SYNOPSIS 45.In util.h 46.Ft int 47.Fn openpty "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp" 48.Ft int 49.Fn login_tty "int fd" 50.Ft pid_t 51.Fn forkpty "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp" 52.Sh DESCRIPTION 53The 54.Fn openpty , 55.Fn login_tty , 56and 57.Fn forkpty 58functions perform manipulations on ttys and pseudo-ttys. 59.Pp 60The 61.Fn openpty 62function finds an available pseudo-tty and returns file descriptors 63for the master and slave in 64.Fa amaster 65and 66.Fa aslave . 67If 68.Fa name 69is non-null, the filename of the slave is returned in 70.Fa name . 71The length of 72.Fa name 73is limited to 74.Dv PATH_MAX 75as any other regular path name, so a buffer of this size should be used. 76.\" .Dv 16 77.\" characters in the current 78.\" .Xr ptm 4 79.\" device driver (including the terminating 80.\" .Dv NUL ) 81.\" which limits the maximum to 82.\" .Dv 100,000 83.\" ptys. 84If 85.Fa termp 86is non-null, the terminal parameters of the slave will be set to the 87values in 88.Fa termp . 89If 90.Fa winp 91is non-null, the window size of the slave will be set to the values in 92.Fa winp . 93.Pp 94The 95.Fn login_tty 96function prepares for a login on the tty 97.Fa fd 98(which may be a real tty device, or the slave of a pseudo-tty as 99returned by 100.Fn openpty ) 101by creating a new session, making 102.Fa fd 103the controlling terminal for the current process, setting 104.Fa fd 105to be the standard input, output, and error streams of the current 106process, and closing 107.Fa fd . 108.Pp 109The 110.Fn forkpty 111function combines 112.Fn openpty , 113.Fn fork , 114and 115.Fn login_tty 116to create a new process operating in a pseudo-tty. 117The file descriptor of the master side of the pseudo-tty is returned 118(to the parent process only) in 119.Fa amaster . 120The filename of the slave is returned (to both the parent and child 121processes) in 122.Fa name 123if 124.Fa name 125is non-null. 126The 127.Fa termp 128and 129.Fa winp 130parameters, if non-null, will determine the terminal attributes and 131window size of the slave side of the pseudo-tty. 132.Sh RETURN VALUES 133If a call to 134.Fn openpty , 135.Fn login_tty , 136or 137.Fn forkpty 138is not successful, -1 is returned and 139.Va errno 140is set to indicate the error. 141Otherwise, 142.Fn openpty , 143.Fn login_tty , 144and the child process of 145.Fn forkpty 146return 0, and the parent process of 147.Fn forkpty 148returns the process ID of the child process. 149.Sh FILES 150.Bl -tag -width /dev/[pt]ty[p-zP-T][0-9a-zA-Z] -compact 151.It Pa /dev/[pt]ty[p-zP-T][0-9a-zA-Z] 152.El 153.Sh ERRORS 154.Fn openpty 155will fail if: 156.Bl -tag -width Er 157.It Bq Er ENOENT 158There are no available ttys. 159.It Bq Er EPERM 160The caller was not the superuser and the 161.Xr ptm 4 162device is missing or not configured. 163.El 164.Pp 165.Fn login_tty 166will fail if 167.Fn ioctl 168fails to set 169.Fa fd 170to the controlling terminal of the current process. 171.Fn forkpty 172will fail if either 173.Fn openpty 174or 175.Fn fork 176fails. 177.Sh SEE ALSO 178.Xr fork 2 179