| blob | 1e4f54b586e12f10a2eba9138a800a440586b09a |
1 .\" $NetBSD: ttyname.3,v 1.20 2008/01/30 19:24:59 apb 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 25, 2008
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
55 These functions operate on the system file descriptors for terminal
56 type devices.
57 These descriptors are not related to the standard
58 .Tn I/O
59 .Dv FILE
60 typedef, but refer to the special device files found in
61 .Pa /dev
62 and named
63 .Pa /dev/tty Ns Em xx
64 and for which an entry exists in the initialization file
65 .Pa /etc/ttys
66 (see
67 .Xr ttys 5 ) ,
68 or for pseudo-terminal devices created in ptyfs and named
69 .Pa /dev/pts/ Ns Em n .
70 .Pp
71 The
72 .Fn isatty
73 function
74 determines if the file descriptor
75 .Fa fd
76 refers to a valid terminal type device.
77 .Pp
78 The
79 .Fn ttyname
80 function gets the related device name of a file descriptor for
81 which
82 .Fn isatty
83 is true.
84 The
85 .Fn ttyname_r
86 is the reentrant version of the above, and it places the results in
87 .Fa buf .
88 If there is not enough space to place the results (indicated by
89 .Fa len ) ,
90 then it returns an error.
91 .Pp
92 The
93 .Fn ttyslot
94 function
95 fetches the current process' control terminal number from the
96 .Xr ttys 5
97 file entry.
98 If the terminal is a pseudo-terminal, and there is no special entry
99 in the
100 .Xr ttys 5
101 file for it, the slot number returned is 1 + (last slot number) +
102 minor(tty).
103 This will return a consistent and unique number for each pseudo-terminal
104 device without requiring one to enumerate all of them in
105 .Xr ttys 5 .
106 .Sh IMPLEMENTATION NOTES
107 As an optimisation, these functions attempt to obtain information about
108 all devices from the
109 .Pa /var/run/dev.db
110 database, if it exists.
111 If the database exists but is out of date, then these functions
112 may produce incorrect results.
113 The database should be updated using the
114 .Xr dev_mkdb 8
115 command.
116 .Sh RETURN VALUES
117 The
118 .Fn ttyname
119 function returns the NUL-terminated name if the device is found and
120 .Fn isatty
121 is true; otherwise
122 a
123 .Dv NULL
124 pointer is returned and
125 .Va errno
126 is set to indicate the error.
127 .Pp
128 The
129 .Fn ttyname_r
130 functions returns 0 on success and an error code on failure.
131 .Pp
132 The
133 .Fn isatty
134 function returns 1 if
135 .Fa fd
136 is associated with a terminal device; otherwise it returns 0 and
137 .Va errno
138 is set to indicate the error.
139 .Pp
140 The
141 .Fn ttyslot
142 function
143 returns the unit number of the device file if found; otherwise
144 the 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
151 The
152 .Fn ttyname ,
153 .Fn ttyname_r ,
154 and
155 .Fn isatty
156 functions will fail if:
157 .Bl -tag -width Er
158 .It Bq Er EBADF
159 The
160 .Fa fd
161 argument is not a valid file descriptor.
162 .It Bq Er ENOTTY
163 The
164 .Fa fd
165 argument does not refer to a terminal device.
166 .El
167 .Pp
168 The
169 .Fn ttyname_r
170 function will also fail if:
171 .Bl -tag -width Er
172 .It Bq Er ERANGE
173 The buffer provided is not large enough to fit the result.
174 .It Bq Er ENOENT
175 The terminal device is not found.
176 This can happen if the device node has been removed after it was opened.
177 .El
178 .Sh SEE ALSO
179 .Xr ioctl 2 ,
180 .Xr ttys 5 ,
181 .Xr dev_mkdb 8
182 .Sh STANDARDS
183 The
184 .Fn ttyname
185 and
186 .Fn isatty
187 functions conform to
188 .St -p1003.1-90 .
189 .Sh HISTORY
190 .Fn isatty ,
191 .Fn ttyname ,
192 and
193 .Fn ttyslot
194 functions appeared in
195 .At v7 .
196 .\" Use of the .Pa /var/run/dev.db file was added in ???.
197 .Sh BUGS
198 The
199 .Fn ttyname
200 function leaves its result in an internal static object and returns
201 a pointer to that object.
202 Subsequent calls to
203 .Fn ttyname
204 will modify the same object.