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.Dd October 14, 2023 33.Dt PTSNAME 3 34.Os 35.Sh NAME 36.Nm grantpt , 37.Nm ptsname , 38.Nm ptsname_r , 39.Nm unlockpt 40.Nd pseudo-terminal access functions 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In stdlib.h 45.Ft int 46.Fn grantpt "int fildes" 47.Ft "char *" 48.Fn ptsname "int fildes" 49.Ft "int" 50.Fn ptsname_r "int fildes" "char *buffer" "size_t buflen" 51.Ft int 52.Fn unlockpt "int fildes" 53.Sh DESCRIPTION 54The 55.Fn grantpt , 56.Fn ptsname , 57and 58.Fn unlockpt 59functions allow access to pseudo-terminal devices. 60These three functions accept a file descriptor that references the 61master half of a pseudo-terminal pair. 62This file descriptor is created with 63.Xr posix_openpt 2 . 64.Pp 65The 66.Fn grantpt 67function is used to establish ownership and permissions 68of the slave device counterpart to the master device 69specified with 70.Fa fildes . 71The slave device's ownership is set to the real user ID 72of the calling process, and the permissions are set to 73user readable-writable and group writable. 74The group owner of the slave device is also set to the 75group 76.Dq Li tty . 77.Pp 78The 79.Fn ptsname 80function returns the full pathname of the slave device 81counterpart to the master device specified with 82.Fa fildes . 83This value can be used 84to subsequently open the appropriate slave after 85.Xr posix_openpt 2 86and 87.Fn grantpt 88have been called. 89.Pp 90The 91.Fn ptsname_r 92function is the thread-safe version of 93.Fn ptsname . 94The caller must provide storage for the results of the full pathname of 95the slave device in the 96.Fa buffer 97and 98.Fa bufsize 99arguments. 100.Pp 101The 102.Fn unlockpt 103function clears the lock held on the pseudo-terminal pair 104for the master device specified with 105.Fa fildes . 106.Sh RETURN VALUES 107.Rv -std grantpt unlockpt 108.Pp 109The 110.Fn ptsname 111function returns a pointer to the name 112of the slave device on success; otherwise a 113.Dv NULL 114pointer is returned. 115.Pp 116The 117.Fn ptsname_r 118function returns the value 0 if successful; 119otherwise a nonzero value is returned and the global variable 120.Va errno 121is set to indicate the error. 122Note: 123.Fn ptsname_r 124was previously documented as returning -1 on error. 125In the future it will be changed to return an error number, for POSIX 126compatibility. 127Therefore, callers should not check for -1. 128.Sh ERRORS 129The 130.Fn grantpt , 131.Fn ptsname , 132.Fn ptsname_r 133and 134.Fn unlockpt 135functions may fail and set 136.Va errno 137to: 138.Bl -tag -width Er 139.It Bq Er EBADF 140.Fa fildes 141is not a valid open file descriptor. 142.It Bq Er EINVAL 143.Fa fildes 144is not a master pseudo-terminal device. 145.El 146.Pp 147In addition, the 148.Fn ptsname_r 149function may set 150.Va errno 151to: 152.Bl -tag -width Er 153.It Bq Er ERANGE 154The buffer was too small. 155.El 156.Pp 157In addition, the 158.Fn grantpt 159function may set 160.Va errno 161to: 162.Bl -tag -width Er 163.It Bq Er EACCES 164The slave pseudo-terminal device could not be accessed. 165.El 166.Sh SEE ALSO 167.Xr posix_openpt 2 , 168.Xr pts 4 , 169.Xr tty 4 170.Sh STANDARDS 171The 172.Fn ptsname 173function conforms to 174.St -p1003.1-2008 . 175.Pp 176This implementation of 177.Fn grantpt 178and 179.Fn unlockpt 180does not conform to 181.St -p1003.1-2008 , 182because it depends on 183.Xr posix_openpt 2 184to create the pseudo-terminal device with proper permissions in place. 185It only validates whether 186.Fa fildes 187is a valid pseudo-terminal master device. 188Future revisions of the specification will likely allow this behaviour, 189as stated by the Austin Group. 190.Sh HISTORY 191The 192.Fn grantpt , 193.Fn ptsname 194and 195.Fn unlockpt 196functions appeared in 197.Fx 5.0 . 198