1.\" $NetBSD: ptsname.3,v 1.9 2014/01/10 09:43:15 wiz Exp $ 2.\" 3.\" Copyright (c) 2004 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Christos Zoulas. 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 7, 2014 31.Dt PTSNAME 3 32.Os 33.Sh NAME 34.Nm ptsname , 35.Nm ptsname_r 36.Nd get the pathname of the slave pseudo-terminal device 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In stdlib.h 41.Ft char * 42.Fn ptsname "int masterfd" 43.Ft char * 44.Fn ptsname_r "int masterfd" "char *buf" "size_t buflen" 45.Sh DESCRIPTION 46The 47.Fn ptsname 48function returns the pathname of the slave pseudo-terminal device 49that corresponds to the master pseudo-terminal device associated with 50.Fa masterfd . 51The 52.Fn ptsname 53function is not reentrant or thread-safe. 54.Pp 55The 56.Fn ptsname_r 57function 58places the pathname of the slave pseudo-terminal device that corresponds 59to the master pseudo-terminal device associated with 60.Fa masterfd 61int the 62.Fa buf 63argument copying up to 64.Fa buflen 65characters. 66The 67.Fa buf 68is always 69.Dv NUL 70terminated. 71.Sh RETURN VALUES 72If successful, 73.Fn ptsname 74returns a pointer to a nul-terminated string containing the pathname 75of the slave pseudo-terminal device. 76If an error occurs 77.Fn ptsname 78will return 79.Dv NULL 80and 81.Va errno 82is set to indicate the error. 83.Pp 84If successful, 85.Fn ptsname_r 86places a nul-terminated string containing the pathname 87of the slave pseudo-terminal device 88in 89.Fa buf 90and returns 91.Dv 0 . 92If an error occurs 93.Fn ptsname_r 94will return 95an error number number indicating what went wrong. 96.Sh ERRORS 97The 98.Fn ptsname 99and 100.Fn ptsname_r 101functions will fail if: 102.Bl -tag -width Er 103.It Bq Er EACCESS 104the corresponding pseudo-terminal device could not be accessed. 105.It Bq Er EBADF 106.Fa masterfd 107is not a valid descriptor. 108.It Bq Er EINVAL 109.Fa masterfd 110is not associated with a master pseudo-terminal device. 111.El 112.Pp 113In addition the 114.Fn ptsname_r 115function 116will return: 117.Bl -tag -width Er 118.It Bq Er EINVAL 119the 120.Fa buf 121argument is 122.Dv NULL . 123.It Bq Er ERANGE 124the name of the pseudo-terminal is longer than 125.Fa bufsiz 126characters plus the terminating 127.Dv NUL . 128.El 129.Sh NOTES 130The error returns of 131.Fn ptsname 132are a 133.Nx 134extension. 135The 136.Fn ptsname 137function is equivalent to: 138.Bd -literal 139 struct ptmget pm; 140 return ioctl(masterfd, TIOCPTSNAME, \*[Am]pm) == -1 ? NULL : pm.sn; 141.Ed 142.Pp 143Both the 144.Fn ptsname 145and 146.Fn ptsname_r 147functions will also return the name of the slave pseudo-terminal if a file 148descriptor to the slave pseudo-terminal is passed to 149.Fa masterfd . 150.Pp 151This is a convenient extension because it allows one to use the file descriptor 152obtained by 153.Xr open 2 154.Pa /dev/tty 155to obtain the name of the pseudo-terminal for the current process. 156.Sh SEE ALSO 157.Xr ioctl 2 , 158.Xr open 2 , 159.Xr grantpt 3 , 160.Xr posix_openpt 3 , 161.Xr unlockpt 3 162.Sh STANDARDS 163The 164.Fn ptsname 165function conforms to 166.St -p1003.1-2001 . 167Its first release was in 168.St -xpg4.2 . 169