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