xref: /dragonfly/lib/libc/gen/ttyname.3 (revision cf89a63b) 
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.\" $DragonFly: src/lib/libc/gen/ttyname.3,v 1.3 2005/11/19 22:32:53 swildner Exp $
31.\"
32.Dd March 22, 2009
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.Ft int
52.Fn ttyslot void
53.Sh DESCRIPTION
54These functions operate on the system file descriptors for terminal
55type devices.
56These descriptors are not related to the standard
57.Tn I/O
58.Dv FILE
59typedef, but refer to the special device files found in
60.Pa /dev
61and named
62.Pa /dev/tty Ns Ar xx
63and for which an entry exists
64in the initialization file
65.Pa /etc/ttys .
66(See
67.Xr ttys 5 . )
68.Pp
69The
70.Fn isatty
71function
72determines if the file descriptor
73.Fa fd
74refers to a valid
75terminal type device.
76.Pp
77The
78.Fn ttyname
79function
80gets the related device name of
81a file descriptor for which
82.Fn isatty
83is true.
84.Pp
85The
86.Fn ttyname
87function
88returns the name stored in a static buffer which will be overwritten
89on subsequent calls.
90The
91.Fn ttyname_r
92function
93takes a buffer and length as arguments to avoid this problem.
94.Pp
95The
96.Fn ttyslot
97function
98fetches the current process' control terminal number from the
99.Xr ttys 5
100file entry.
101.Sh RETURN VALUES
102The
103.Fn isatty
104function
105returns 1 if the file descriptor refers to a valid terminal
106device and 0 otherwise.
107.Pp
108The
109.Fn ttyname
110function
111returns the null terminated name if the device is found and
112.Fn isatty
113is true; otherwise
114a
115.Dv NULL
116pointer is returned.
117The
118.Fn ttyname_r
119function returns 0 if successful.
120Otherwise an error number is returned.
121.Pp
122The
123.Fn ttyslot
124function
125returns the unit number of the device file if found; otherwise
126the value zero is returned.
127.Sh FILES
128.Bl -tag -width ".Pa /etc/ttys" -compact
129.It Pa /dev/\(**
130.It Pa /etc/ttys
131.El
132.Sh ERRORS
133The
134.Fn ttyname ,
135.Fn ttyname_r ,
136and
137.Fn isatty
138functions
139may fail and return the following error codes:
140.Bl -tag -width Er
141.It Bq Er EBADF
142The
143.Fa fd
144is not a valid open file descriptor.
145.It Bq Er ENOTTY
146The
147.Fa fd
148is not associated with a terminal.
149.It Bq Er ERANGE
150The
151.Fa bufsize
152argument
153is smaller than the length of the string to be returned.
154.El
155.Sh SEE ALSO
156.Xr ioctl 2 ,
157.Xr ttys 5
158.Sh HISTORY
159The
160.Fn isatty ,
161.Fn ttyname ,
162and
163.Fn ttyslot
164functions
165appeared in
166.At v7 .
167The
168.Fn ttyname_r
169function
170appeared in
171.Fx 6.0 .
172