1.\" $OpenBSD: ttyname.3,v 1.20 2022/10/13 21:37:05 jmc Exp $ 2.\" 3.\" Copyright (c) 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: October 13 2022 $ 31.Dt TTYNAME 3 32.Os 33.Sh NAME 34.Nm ttyname , 35.Nm ttyname_r , 36.Nm isatty , 37.Nm ttyslot 38.Nd get name of associated terminal (tty) from file descriptor 39.Sh SYNOPSIS 40.In unistd.h 41.Ft char * 42.Fn ttyname "int fd" 43.Ft int 44.Fn ttyname_r "int fd" "char *name" "size_t namesize" 45.Ft int 46.Fn isatty "int fd" 47.In stdlib.h 48.Ft int 49.Fn ttyslot "void" 50.Sh DESCRIPTION 51These functions operate on the system file descriptors for terminal 52type devices. 53These descriptors are not related to the standard 54.Tn I/O 55.Dv FILE 56typedef, but refer to the special device files found in 57.Pa /dev 58and named 59.Pa /dev/tty Ns Em XX 60and for which an entry exists 61in the initialization file 62.Pa /etc/ttys 63(see 64.Xr ttys 5 ) . 65.Pp 66The 67.Fn isatty 68function determines if the file descriptor 69.Fa fd 70refers to a valid 71terminal type device. 72.Pp 73The 74.Fn ttyname 75and 76.Fn ttyname_r 77functions get the related device name of a file descriptor for which 78.Fn isatty 79is true. 80The 81.Fn ttyname_r 82function stores the NUL-terminated 83pathname of the terminal associated with 84the file descriptor 85.Fa fd 86in the character array referenced by 87.Fa name . 88The array is 89.Fa namesize 90characters long and should have space for the name and the terminating 91NUL character. 92The maximum length of the terminal name is 93.Dv TTY_NAME_MAX . 94.Pp 95The 96.Fn ttyslot 97function fetches the current process's controlling terminal number from 98the 99.Xr ttys 5 100file entry. 101.Sh RETURN VALUES 102The 103.Fn ttyname 104function returns the NUL-terminated name if the device is found and 105.Fn isatty 106is true; otherwise 107a null pointer is returned and 108.Va errno 109is set to indicate the error. 110.Pp 111The 112.Fn ttyname_r 113function returns zero if successful; otherwise an error number is returned. 114.Pp 115The 116.Fn isatty 117function returns 1 if 118.Fa fd 119is associated with a terminal device; otherwise it returns 0 and 120.Va errno 121is set to indicate the error. 122.Pp 123The 124.Fn ttyslot 125function returns the unit number of the device file if found; otherwise 126the value zero is returned. 127.Sh FILES 128.Bl -tag -width /etc/ttys -compact 129.It Pa /dev/\(** 130.It Pa /etc/ttys 131.El 132.Sh ERRORS 133The 134.Fn ttyname , 135.Fn ttyname_r , 136and 137.Fn isatty 138functions will fail if: 139.Bl -tag -width Er 140.It Bq Er EBADF 141The 142.Fa fd 143argument is not a valid file descriptor. 144.It Bq Er ENOTTY 145The 146.Fa fd 147argument does not refer to a terminal device. 148.It Bq Er ERANGE 149The value of 150.Fa namesize 151is smaller than the length of the string to be returned including the 152terminating NUL character. 153.El 154.Sh SEE ALSO 155.Xr ioctl 2 , 156.Xr ttys 5 , 157.Xr dev_mkdb 8 158.Sh HISTORY 159The 160.Fn isatty , 161.Fn ttyname , 162and 163.Fn ttyslot 164functions appeared in 165.At v7 . 166The 167.Fn ttyname_r 168function appeared in the POSIX Threads Extension (1003.1c-1995). 169.Sh BUGS 170The 171.Fn ttyname 172function leaves its result in an internal static object and returns 173a pointer to that object. 174Subsequent calls to 175.Fn ttyname 176will modify the same object. 177