1.\" 2.\" Copyright (c) 2002 The FreeBSD Project, Inc. 3.\" All rights reserved. 4.\" 5.\" This software includes code contributed to the FreeBSD Project 6.\" by Ryan Younce of North Carolina State University. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the FreeBSD Project nor the names of its 17.\" contributors may be used to endorse or promote products derived from 18.\" this software without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE FREEBSD PROJECT AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 23.\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD PROJECT 24.\" OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 26.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.\" $FreeBSD$ 33.\" 34.Dd October 17, 2020 35.Dt PTSNAME 3 36.Os 37.Sh NAME 38.Nm grantpt , 39.Nm ptsname , 40.Nm ptsname_r , 41.Nm unlockpt 42.Nd pseudo-terminal access functions 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdlib.h 47.Ft int 48.Fn grantpt "int fildes" 49.Ft "char *" 50.Fn ptsname "int fildes" 51.Ft "int" 52.Fn ptsname_r "int fildes" "char *buffer" "size_t buflen" 53.Ft int 54.Fn unlockpt "int fildes" 55.Sh DESCRIPTION 56The 57.Fn grantpt , 58.Fn ptsname , 59and 60.Fn unlockpt 61functions allow access to pseudo-terminal devices. 62These three functions accept a file descriptor that references the 63master half of a pseudo-terminal pair. 64This file descriptor is created with 65.Xr posix_openpt 2 . 66.Pp 67The 68.Fn grantpt 69function is used to establish ownership and permissions 70of the slave device counterpart to the master device 71specified with 72.Fa fildes . 73The slave device's ownership is set to the real user ID 74of the calling process, and the permissions are set to 75user readable-writable and group writable. 76The group owner of the slave device is also set to the 77group 78.Dq Li tty . 79.Pp 80The 81.Fn ptsname 82function returns the full pathname of the slave device 83counterpart to the master device specified with 84.Fa fildes . 85This value can be used 86to subsequently open the appropriate slave after 87.Xr posix_openpt 2 88and 89.Fn grantpt 90have been called. 91.Pp 92The 93.Fn ptsname_r 94function is the thread-safe version of 95.Fn ptsname . 96The caller must provide storage for the results of the full pathname of 97the slave device in the 98.Fa buffer 99and 100.Fa bufsize 101arguments. 102.Pp 103The 104.Fn unlockpt 105function clears the lock held on the pseudo-terminal pair 106for the master device specified with 107.Fa fildes . 108.Sh RETURN VALUES 109.Rv -std grantpt ptsname_r unlockpt 110.Pp 111The 112.Fn ptsname 113function returns a pointer to the name 114of the slave device on success; otherwise a 115.Dv NULL 116pointer is returned. 117.Sh ERRORS 118The 119.Fn grantpt , 120.Fn ptsname , 121.Fn ptsname_r 122and 123.Fn unlockpt 124functions may fail and set 125.Va errno 126to: 127.Bl -tag -width Er 128.It Bq Er EBADF 129.Fa fildes 130is not a valid open file descriptor. 131.It Bq Er EINVAL 132.Fa fildes 133is not a master pseudo-terminal device. 134.El 135.Pp 136In addition, the 137.Fn ptsname_r 138function may set 139.Va errno 140to: 141.Bl -tag -width Er 142.It Bq Er ERANGE 143The buffer was too small. 144.El 145.Pp 146In addition, the 147.Fn grantpt 148function may set 149.Va errno 150to: 151.Bl -tag -width Er 152.It Bq Er EACCES 153The slave pseudo-terminal device could not be accessed. 154.El 155.Sh SEE ALSO 156.Xr posix_openpt 2 , 157.Xr pts 4 , 158.Xr tty 4 159.Sh STANDARDS 160The 161.Fn ptsname 162function conforms to 163.St -p1003.1-2008 . 164.Pp 165This implementation of 166.Fn grantpt 167and 168.Fn unlockpt 169does not conform to 170.St -p1003.1-2008 , 171because it depends on 172.Xr posix_openpt 2 173to create the pseudo-terminal device with proper permissions in place. 174It only validates whether 175.Fa fildes 176is a valid pseudo-terminal master device. 177Future revisions of the specification will likely allow this behaviour, 178as stated by the Austin Group. 179.Sh HISTORY 180The 181.Fn grantpt , 182.Fn ptsname 183and 184.Fn unlockpt 185functions appeared in 186.Fx 5.0 . 187