Retire the utmp specific ttyslot() function, like FreeBSD did.
[dragonfly.git] / lib / libc / gen / ttyname.3
1 .\" Copyright (c) 1991, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\"    may be used to endorse or promote products derived from this software
14 .\"    without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\"     @(#)ttyname.3   8.1 (Berkeley) 6/4/93
29 .\" $FreeBSD: src/lib/libc/gen/ttyname.3,v 1.14 2007/01/09 00:27:55 imp Exp $
30 .\"
31 .Dd September 10, 2019
32 .Dt TTYNAME 3
33 .Os
34 .Sh NAME
35 .Nm ttyname ,
36 .Nm ttyname_r ,
37 .Nm isatty
38 .Nd get name of associated terminal (tty) from file descriptor
39 .Sh LIBRARY
40 .Lb libc
41 .Sh SYNOPSIS
42 .In unistd.h
43 .Ft char *
44 .Fn ttyname "int fd"
45 .Ft int
46 .Fn ttyname_r "int fd" "char *buf" "size_t len"
47 .Ft int
48 .Fn isatty "int fd"
49 .Sh DESCRIPTION
50 These functions operate on the system file descriptors for terminal
51 type devices.
52 These descriptors are not related to the standard
53 .Tn I/O
54 .Dv FILE
55 typedef, but refer to the special device files found in
56 .Pa /dev
57 and named
58 .Pa /dev/tty Ns Ar xx
59 and for which an entry exists
60 in the initialization file
61 .Pa /etc/ttys .
62 (See
63 .Xr ttys 5 . )
64 .Pp
65 The
66 .Fn isatty
67 function
68 determines if the file descriptor
69 .Fa fd
70 refers to a valid
71 terminal type device.
72 .Pp
73 The
74 .Fn ttyname
75 function
76 gets the related device name of
77 a file descriptor for which
78 .Fn isatty
79 is true.
80 .Pp
81 The
82 .Fn ttyname
83 function
84 returns the name stored in a static buffer which will be overwritten
85 on subsequent calls.
86 The
87 .Fn ttyname_r
88 function
89 takes a buffer and length as arguments to avoid this problem.
90 .Sh RETURN VALUES
91 The
92 .Fn isatty
93 function
94 returns 1 if the file descriptor refers to a valid terminal
95 device and 0 otherwise.
96 .Pp
97 The
98 .Fn ttyname
99 function
100 returns the null terminated name if the device is found and
101 .Fn isatty
102 is true; otherwise
103 a
104 .Dv NULL
105 pointer is returned.
106 The
107 .Fn ttyname_r
108 function returns 0 if successful.
109 Otherwise an error number is returned.
110 .Sh FILES
111 .Bl -tag -width ".Pa /etc/ttys" -compact
112 .It Pa /dev/\(**
113 .It Pa /etc/ttys
114 .El
115 .Sh ERRORS
116 The
117 .Fn ttyname ,
118 .Fn ttyname_r ,
119 and
120 .Fn isatty
121 functions
122 may fail and return the following error codes:
123 .Bl -tag -width Er
124 .It Bq Er EBADF
125 The
126 .Fa fd
127 is not a valid open file descriptor.
128 .It Bq Er ENOTTY
129 The
130 .Fa fd
131 is not associated with a terminal.
132 .It Bq Er ERANGE
133 The
134 .Fa bufsize
135 argument
136 is smaller than the length of the string to be returned.
137 .El
138 .Sh SEE ALSO
139 .Xr ioctl 2 ,
140 .Xr ttys 5
141 .Sh HISTORY
142 The
143 .Fn isatty
144 and
145 .Fn ttyname
146 functions
147 appeared in
148 .At v7 .
149 The
150 .Fn ttyname_r
151 function
152 appeared in
153 .Fx 6.0 .