1.\" $OpenBSD: ttyname.3,v 1.19 2013/11/12 05:12:15 deraadt 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: November 12 2013 $ 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 control terminal number from the 98.Xr ttys 5 99file entry. 100.Sh RETURN VALUES 101The 102.Fn ttyname 103function returns the NUL-terminated name if the device is found and 104.Fn isatty 105is true; otherwise 106a null pointer is returned and 107.Va errno 108is set to indicate the error. 109.Pp 110The 111.Fn ttyname_r 112function returns zero if successful; otherwise an error number is returned. 113.Pp 114The 115.Fn isatty 116function returns 1 if 117.Fa fd 118is associated with a terminal device; otherwise it returns 0 and 119.Va errno 120is set to indicate the error. 121.Pp 122The 123.Fn ttyslot 124function returns the unit number of the device file if found; otherwise 125the value zero is returned. 126.Sh FILES 127.Bl -tag -width /etc/ttys -compact 128.It Pa /dev/\(** 129.It Pa /etc/ttys 130.El 131.Sh ERRORS 132The 133.Fn ttyname , 134.Fn ttyname_r , 135and 136.Fn isatty 137functions will fail if: 138.Bl -tag -width Er 139.It Bq Er EBADF 140The 141.Fa fd 142argument is not a valid file descriptor. 143.It Bq Er ENOTTY 144The 145.Fa fd 146argument does not refer to a terminal device. 147.It Bq Er ERANGE 148The value of 149.Fa namesize 150is smaller than the length of the string to be returned including the 151terminating NUL character. 152.El 153.Sh SEE ALSO 154.Xr ioctl 2 , 155.Xr ttys 5 , 156.Xr dev_mkdb 8 157.Sh HISTORY 158The 159.Fn isatty , 160.Fn ttyname , 161and 162.Fn ttyslot 163functions appeared in 164.At v7 . 165The 166.Fn ttyname_r 167function appeared in the POSIX Threads Extension (1003.1c-1995). 168.Sh BUGS 169The 170.Fn ttyname 171function leaves its result in an internal static object and returns 172a pointer to that object. 173Subsequent calls to 174.Fn ttyname 175will modify the same object. 176