Merge from vendor branch BZIP:
[dragonfly.git] / lib / libc / gen / ttyname.3
CommitLineData
984263bc
MD
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. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)ttyname.3 8.1 (Berkeley) 6/4/93
33.\" $FreeBSD: src/lib/libc/gen/ttyname.3,v 1.5.2.3 2001/12/14 18:33:51 ru Exp $
b0e25abd 34.\" $DragonFly: src/lib/libc/gen/ttyname.3,v 1.3 2005/11/19 22:32:53 swildner Exp $
984263bc
MD
35.\"
36.Dd June 4, 1993
37.Dt TTYNAME 3
38.Os
39.Sh NAME
40.Nm ttyname ,
41.Nm isatty ,
42.Nm ttyslot
43.Nd get name of associated terminal (tty) from file descriptor
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In unistd.h
48.Ft char *
49.Fn ttyname "int fd"
b0e25abd
SW
50.Ft char *
51.Fn ttyname_r "int fd" "char *buf" "size_t len"
984263bc
MD
52.Ft int
53.Fn isatty "int fd"
54.Ft int
55.Fn ttyslot void
56.Sh DESCRIPTION
57These functions operate on the system file descriptors for terminal
58type devices.
59These descriptors are not related to the standard
60.Tn I/O
61.Dv FILE
62typedef, but refer to the special device files found in
63.Pa /dev
64and named
65.Pa /dev/tty Ns Em xx
66and for which an entry exists
67in the initialization file
68.Pa /etc/ttys .
69(See
70.Xr ttys 5 . )
71.Pp
72The
73.Fn isatty
74function
75determines if the file descriptor
76.Fa fd
77refers to a valid
78terminal type device.
79.Pp
80The
81.Fn ttyname
82function
83gets the related device name of
84a file descriptor for which
85.Fn isatty
86is true
87.Pp
88The
b0e25abd
SW
89.Fn ttyname_r
90function is a thread-safe version of
91.Fn ttyname
92.Pp
93The
984263bc
MD
94.Fn ttyslot
95function
96fetches the current process' control terminal number from the
97.Xr ttys 5
98file entry.
99.Sh RETURN VALUES
100The
101.Fn ttyname
102function
103returns the null terminated name if the device is found and
104.Fn isatty
105is true; otherwise
106a
107.Dv NULL
108pointer is returned.
109.Pp
110The
111.Fn ttyslot
112function
113returns the unit number of the device file if found; otherwise
114the value zero is returned.
115.Sh FILES
116.Bl -tag -width /etc/ttys -compact
117.It Pa /dev/\(**
118.It Pa /etc/ttys
119.El
120.Sh SEE ALSO
121.Xr ioctl 2 ,
122.Xr ttys 5
123.Sh HISTORY
124A
125.Fn isatty ,
126.Fn ttyname ,
127and
128.Fn ttyslot
129function
130appeared in
131.At v7 .
132.Sh BUGS
133The
134.Fn ttyname
135function leaves its result in an internal static object and returns
136a pointer to that object.
137Subsequent calls to
138.Fn ttyname
139will modify the same object.