1.\" $NetBSD: ttyname.3,v 1.19 2005/09/26 10:54:46 wiz 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.\" @(#)ttyname.3 8.1 (Berkeley) 6/4/93 31.\" 32.Dd September 25, 2005 33.Dt TTYNAME 3 34.Os 35.Sh NAME 36.Nm ttyname , 37.Nm ttyname_r , 38.Nm isatty , 39.Nm ttyslot 40.Nd get name of associated terminal (tty) from file descriptor 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In unistd.h 45.Ft char * 46.Fn ttyname "int fd" 47.Ft int 48.Fn ttyname_r "int fd" "char *buf" "size_t len" 49.Ft int 50.Fn isatty "int fd" 51.In stdlib.h 52.Ft int 53.Fn ttyslot 54.Sh DESCRIPTION 55These functions operate on the system file descriptors for terminal 56type devices. 57These descriptors are not related to the standard 58.Tn I/O 59.Dv FILE 60typedef, but refer to the special device files found in 61.Pa /dev 62and named 63.Pa /dev/tty Ns Em xx 64and for which an entry exists in the initialization file 65.Pa /etc/ttys 66(see 67.Xr ttys 5 ) , 68or for pseudo-terminal devices created in ptyfs and named 69.Pa /dev/pts/ Ns Em n . 70.Pp 71The 72.Fn isatty 73function 74determines if the file descriptor 75.Fa fd 76refers to a valid terminal type device. 77.Pp 78The 79.Fn ttyname 80function gets the related device name of a file descriptor for 81which 82.Fn isatty 83is true. 84The 85.Fn ttyname_r 86is the reentrant version of the above, and it places the results in 87.Fa buf . 88If there is not enough space to place the results (indicated by 89.Fa len ) , 90then it returns \-1 and 91.Va errno 92is set to indicate the error. 93.Pp 94The 95.Fn ttyslot 96function 97fetches the current process' control terminal number from the 98.Xr ttys 5 99file entry. 100If the terminal is a pseudo-terminal, and there is no special entry 101in the 102.Xr ttys 5 103file for it, the slot number returned is 1 + (last slot number) + 104minor(tty). 105This will return a consistent and unique number for each pseudo-terminal 106device without requiring one to enumerate all of them in 107.Xr ttys 5 . 108.Sh RETURN VALUES 109The 110.Fn ttyname 111function returns the NUL-terminated name if the device is found and 112.Fn isatty 113is true; otherwise 114a 115.Dv NULL 116pointer is returned and 117.Va errno 118is set to indicate the error. 119.Pp 120The 121.Fn ttyname_r 122functions returns 0 on success and \-1 on failure with 123.Va errno 124set to indicate the error. 125.Pp 126The 127.Fn isatty 128function returns 1 if 129.Fa fd 130is associated with a terminal device; otherwise it returns 0 and 131.Va errno 132is set to indicate the error. 133.Pp 134The 135.Fn ttyslot 136function 137returns the unit number of the device file if found; otherwise 138the value zero is returned. 139.Sh FILES 140.Bl -tag -width /etc/ttys -compact 141.It Pa /dev/\(** 142.It Pa /etc/ttys 143.El 144.Sh ERRORS 145The 146.Fn ttyname , 147.Fn ttyname_r , 148and 149.Fn isatty 150functions will fail if: 151.Bl -tag -width Er 152.It Bq Er EBADF 153The 154.Fa fd 155argument is not a valid file descriptor. 156.It Bq Er ENOTTY 157The 158.Fa fd 159argument does not refer to a terminal device. 160.El 161The 162.Fn ttyname_r 163function will also fail if: 164.Bl -tag -width Er 165.It Bq Er ERANGE 166The buffer provided is not large enough to fit the result. 167.It Bq Er ENOENT 168The terminal device is not found. 169This can happen if the device node has been removed after it was opened. 170.El 171.Sh SEE ALSO 172.Xr ioctl 2 , 173.Xr ttys 5 174.Sh STANDARDS 175The 176.Fn ttyname 177and 178.Fn isatty 179functions conform to 180.St -p1003.1-90 . 181.Sh HISTORY 182.Fn isatty , 183.Fn ttyname , 184and 185.Fn ttyslot 186functions appeared in 187.At v7 . 188.Sh BUGS 189The 190.Fn ttyname 191function leaves its result in an internal static object and returns 192a pointer to that object. 193Subsequent calls to 194.Fn ttyname 195will modify the same object. 196