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