1.\" 2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 3.\" permission to reproduce portions of its copyrighted documentation. 4.\" Original documentation from The Open Group can be obtained online at 5.\" http://www.opengroup.org/bookstore/. 6.\" 7.\" The Institute of Electrical and Electronics Engineers and The Open 8.\" Group, have given us permission to reprint portions of their 9.\" documentation. 10.\" 11.\" In the following statement, the phrase ``this text'' refers to portions 12.\" of the system documentation. 13.\" 14.\" Portions of this text are reprinted and reproduced in electronic form 15.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 16.\" Standard for Information Technology -- Portable Operating System 17.\" Interface (POSIX), The Open Group Base Specifications Issue 6, 18.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 19.\" Engineers, Inc and The Open Group. In the event of any discrepancy 20.\" between these versions and the original IEEE and The Open Group 21.\" Standard, the original IEEE and The Open Group Standard is the referee 22.\" document. The original Standard can be obtained online at 23.\" http://www.opengroup.org/unix/online.html. 24.\" 25.\" This notice shall appear on any product containing this material. 26.\" 27.\" The contents of this file are subject to the terms of the 28.\" Common Development and Distribution License (the "License"). 29.\" You may not use this file except in compliance with the License. 30.\" 31.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 32.\" or http://www.opensolaris.org/os/licensing. 33.\" See the License for the specific language governing permissions 34.\" and limitations under the License. 35.\" 36.\" When distributing Covered Code, include this CDDL HEADER in each 37.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 38.\" If applicable, add the following below this CDDL HEADER, with the 39.\" fields enclosed by brackets "[]" replaced with your own identifying 40.\" information: Portions Copyright [yyyy] [name of copyright owner] 41.\" 42.\" 43.\" Copyright 1989 AT&T 44.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved 45.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. 46.\" Copyright 2024 Oxide Computer Company 47.\" 48.Dd July 2, 2024 49.Dt PTSNAME 3C 50.Os 51.Sh NAME 52.Nm ptsname , 53.Nm ptsname_r 54.Nd get the name of the subsidiary device of a pseudo-terminal 55.Sh SYNOPSIS 56.In stdlib.h 57.Ft char * 58.Fo ptsname 59.Fa "int fildes" 60.Fc 61.Ft int 62.Fo ptsname_r 63.Fa "int fildes" 64.Fa "char *name" 65.Fa "size_t namelen" 66.Fc 67.Sh DESCRIPTION 68The 69.Fn ptsname 70function returns the name of the pseudo-terminal subsidiary device associated 71with a pseudo-terminal manager device. 72The 73.Fa fildes 74argument is a file descriptor returned from a successful open of the 75pseudo-terminal manager device; e.g., by calling 76.Xr posix_openpt 3C 77or by performing an 78.Xr open 2 79of the 80.Xr ptm 4D 81device. 82.Pp 83The 84.Fn ptsname 85function returns a pointer to a string containing the null-terminated 86path name of the subsidiary device. 87This string is of the form 88.Pa /dev/pts/N , 89where 90.Sy N 91is a non-negative integer. 92Callers should generally assume that a subsequent call to 93.Fn ptsname 94will overwrite the returned buffer. 95POSIX does not require that the interface be thread-safe. 96While a per-thread buffer is currently being used, that should not be relied 97upon by portable applications and is not a system guarantee. 98.Pp 99The 100.Fn ptsname_r 101function behaves similarly to the 102.Fn ptsname 103function, but rather than use a thread-specific buffer, stores the name of the 104pseudo-terminal subsidiary device of 105.Fa fildes 106in 107.Fa name . 108The size of 109.Fa name 110is indicated by 111.Fa namelen . 112If the buffer is not large enough, then the function will fail with 113.Er ERANGE . 114The name's length will not exceed 115.Brq TTY_NAME_MAX , 116which can be determined at runtime by calling 117.Xr sysconf 3C 118with the name 119.Dv _SC_TTY_NAME_MAX . 120.Sh RETURN VALUES 121Upon successful completion, the 122.Fn ptsname 123function returns a pointer to a string which is the name of the pseudo-terminal 124subsidiary device. 125This value points to a static data area that is overwritten by each call to 126.Fn ptsname 127by the same thread. 128Otherwise, 129.Dv NULL 130is returned and 131.Va errno 132is set to indicate the error that occurred. 133.Pp 134Upon successful completion, the 135.Fn ptsname_r 136function will return 137.Sy 0 138and 139.Fa name 140will be filled in with the subsidiary device's name. 141Otherwise, an error number will be returned. 142.Sh ERRORS 143The 144.Fn ptsname 145and 146.Fn ptsname_r 147functions will fail if: 148.Bl -tag -width Er 149.It Er EBADF 150The file descriptor, 151.Fa fildes , 152does not refer to a valid file descriptor. 153.It Er EINVAL 154The file descriptor, 155.Fa fildes , 156does not refer to a manager pseudo-terminal device. 157.Pp 158For the 159.Fn ptsname_r 160function, 161.Fa name 162is a 163.Dv NULL 164pointer. 165.It Er ENOTTY 166The file descriptor, 167.Fa fildes , 168does not refer to a manager pseudo-terminal device. 169.It Er ERANGE 170For the 171.Fn ptsname_r 172function, the buffer 173.Fa name 's 174size as indicated by 175.Fa namelen 176was too small to hold the actual subsidiary device's name. 177.El 178.Sh INTERFACE STABILITY 179.Sy Committed 180.Sh MT LEVEL 181The 182.Fn ptsname 183function is 184.Sy Safe . 185.Pp 186The 187.Fn ptsname_r 188function is 189.Sy MT-Safe . 190.Sh SEE ALSO 191.Xr open 2 , 192.Xr grantpt 3C , 193.Xr posix_openpt 3C , 194.Xr ttyname 3C , 195.Xr unlockpt 3C , 196.Xr ptm 4D , 197.Xr pts 4D , 198.Xr attributes 7 , 199.Xr standards 7 200