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 17, 2020 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 ptsname_r 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.Sh ERRORS 116The 117.Fn grantpt , 118.Fn ptsname , 119.Fn ptsname_r 120and 121.Fn unlockpt 122functions may fail and set 123.Va errno 124to: 125.Bl -tag -width Er 126.It Bq Er EBADF 127.Fa fildes 128is not a valid open file descriptor. 129.It Bq Er EINVAL 130.Fa fildes 131is not a master pseudo-terminal device. 132.El 133.Pp 134In addition, the 135.Fn ptsname_r 136function may set 137.Va errno 138to: 139.Bl -tag -width Er 140.It Bq Er ERANGE 141The buffer was too small. 142.El 143.Pp 144In addition, the 145.Fn grantpt 146function may set 147.Va errno 148to: 149.Bl -tag -width Er 150.It Bq Er EACCES 151The slave pseudo-terminal device could not be accessed. 152.El 153.Sh SEE ALSO 154.Xr posix_openpt 2 , 155.Xr pts 4 , 156.Xr tty 4 157.Sh STANDARDS 158The 159.Fn ptsname 160function conforms to 161.St -p1003.1-2008 . 162.Pp 163This implementation of 164.Fn grantpt 165and 166.Fn unlockpt 167does not conform to 168.St -p1003.1-2008 , 169because it depends on 170.Xr posix_openpt 2 171to create the pseudo-terminal device with proper permissions in place. 172It only validates whether 173.Fa fildes 174is a valid pseudo-terminal master device. 175Future revisions of the specification will likely allow this behaviour, 176as stated by the Austin Group. 177.Sh HISTORY 178The 179.Fn grantpt , 180.Fn ptsname 181and 182.Fn unlockpt 183functions appeared in 184.Fx 5.0 . 185