1.\" $NetBSD: ttyname.3,v 1.24 2012/06/03 21:42:46 joerg 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 June 1, 2012 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 "void" 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 an error. 91.Pp 92The 93.Fn ttyslot 94function 95fetches the current process' control terminal number from the 96.Xr ttys 5 97file entry. 98If the terminal is a pseudo-terminal, and there is no special entry 99in the 100.Xr ttys 5 101file for it, the slot number returned is 1 + (last slot number) + 102minor(tty). 103This will return a consistent and unique number for each pseudo-terminal 104device without requiring one to enumerate all of them in 105.Xr ttys 5 . 106.Sh IMPLEMENTATION NOTES 107As an optimisation, these functions attempt to obtain information about 108all devices from the 109.Pa /var/run/dev.cdb 110database, if it exists. 111If the database exists but is out of date, then these functions 112may produce incorrect results. 113The database should be updated using the 114.Xr dev_mkdb 8 115command. 116.Sh RETURN VALUES 117The 118.Fn ttyname 119function returns the NUL-terminated name if the device is found and 120.Fn isatty 121is true; otherwise 122a 123.Dv NULL 124pointer is returned and 125.Va errno 126is set to indicate the error. 127.Pp 128The 129.Fn ttyname_r 130functions returns 0 on success and an error code on failure. 131.Pp 132The 133.Fn isatty 134function returns 1 if 135.Fa fd 136is associated with a terminal device; otherwise it returns 0 and 137.Va errno 138is set to indicate the error. 139.Pp 140The 141.Fn ttyslot 142function 143returns the unit number of the device file if found; otherwise 144the value zero is returned. 145.Sh FILES 146.Bl -tag -width /etc/ttys -compact 147.It Pa /dev/\(** 148.It Pa /etc/ttys 149.El 150.Sh ERRORS 151The 152.Fn ttyname , 153.Fn ttyname_r , 154and 155.Fn isatty 156functions will fail if: 157.Bl -tag -width Er 158.It Bq Er EBADF 159The 160.Fa fd 161argument is not a valid file descriptor. 162.It Bq Er ENOTTY 163The 164.Fa fd 165argument does not refer to a terminal device. 166.El 167.Pp 168The 169.Fn ttyname_r 170function will also fail if: 171.Bl -tag -width Er 172.It Bq Er ENOENT 173The terminal device is not found. 174This can happen if the device node has been removed after it was opened. 175.It Bq Er ERANGE 176The buffer provided is not large enough to fit the result. 177.El 178.Sh SEE ALSO 179.Xr ioctl 2 , 180.Xr ttys 5 , 181.Xr dev_mkdb 8 182.Sh STANDARDS 183The 184.Fn ttyname 185and 186.Fn isatty 187functions conform to 188.St -p1003.1-90 . 189.Sh HISTORY 190.Fn isatty , 191.Fn ttyname , 192and 193.Fn ttyslot 194functions appeared in 195.At v7 . 196.\" Use of the .Pa /var/run/dev.cdb file was added in netBSD 6.0. 197.Sh BUGS 198The 199.Fn ttyname 200function leaves its result in an internal static object and returns 201a pointer to that object. 202Subsequent calls to 203.Fn ttyname 204will modify the same object. 205