1.\" 2.\" Copyright (c) 1996 Joerg Wunsch 3.\" 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" " 26.Dd June 2, 2018 27.Dt PTY 3 28.Os 29.Sh NAME 30.Nm openpty , 31.Nm forkpty 32.Nd auxiliary functions to obtain a pseudo-terminal 33.Sh LIBRARY 34.Lb libutil 35.Sh SYNOPSIS 36.In sys/types.h 37.In sys/ioctl.h 38.In termios.h 39.In libutil.h 40.Ft int 41.Fn openpty "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp" 42.Ft int 43.Fn forkpty "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp" 44.Sh DESCRIPTION 45The function 46.Fn openpty 47attempts to obtain the next available pseudo-terminal from the system (see 48.Xr pty 4 ) . 49If it successfully finds one, it subsequently changes the 50ownership of the slave device to the real UID of the current process, 51the group membership to the group 52.Dq tty 53(if such a group exists in the system), the access permissions for 54reading and writing by the owner, and for writing by the group, and 55invalidates any current use of the line by calling 56.Xr revoke 2 . 57.Pp 58If the argument 59.Fa name 60is not 61.Dv NULL , 62.Fn openpty 63copies the pathname of the slave pty to this area. 64The caller is 65responsible for allocating the required space in this array. 66.Pp 67If the arguments 68.Fa termp 69or 70.Fa winp 71are not 72.Dv NULL , 73.Fn openpty 74initializes the termios and window size settings from the structures 75these arguments point to, respectively. 76.Pp 77Upon return, the open file descriptors for the master and slave side 78of the pty are returned in the locations pointed to by 79.Fa amaster 80and 81.Fa aslave , 82respectively. 83.Pp 84The 85.Fn forkpty 86function first calls 87.Fn openpty 88to obtain the next available pseudo-terminal from the system. 89Upon success, 90it forks off a new process. 91In the child process, it closes the descriptor 92for the master side of the pty, and calls 93.Xr login_tty 3 94for the slave pty. 95In the parent process, it closes the descriptor for the 96slave side of the pty. 97The arguments 98.Fa amaster , 99.Fa name , 100.Fa termp , 101and 102.Fa winp 103have the same meaning as described for 104.Fn openpty . 105.Sh RETURN VALUES 106The 107.Fn openpty 108function returns 0 on success, or -1 on failure. 109.Pp 110The 111.Fn forkpty 112function returns -1 on failure, 0 in the slave process, and the process ID of 113the slave process in the parent process. 114.Sh ERRORS 115The 116.Fn openpty 117function may fail and set the global variable 118.Dv errno 119for any of the errors specified for the 120.Xr grantpt 3 , 121.Xr posix_openpt 2 , 122.Xr ptsname 3 , 123and 124.Xr unlockpt 3 125functions and the 126.Xr revoke 2 127system call. 128.Pp 129In addition to this, 130.Fn forkpty 131may set it to any value as described for 132.Xr fork 2 . 133.Sh SEE ALSO 134.Xr chmod 2 , 135.Xr chown 2 , 136.Xr fork 2 , 137.Xr getuid 2 , 138.Xr open 2 , 139.Xr revoke 2 , 140.Xr login_tty 3 , 141.Xr pty 4 , 142.Xr termios 4 , 143.Xr group 5 144.Sh HISTORY 145The 146.Fn openpty 147and 148.Fn forkpty 149functions first appeared in 150.Bx 4.3 Reno . 151.Sh BUGS 152.Fn openpty 153writes the slave terminal's name to 154.Fa name , 155but does not check that sufficient space is available. 156It is advisable to use 157.Xr ptsname 3 158instead. 159