[apple/libc.git] / gen / FreeBSD / ttyname.3

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