[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. 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$
.\"
.Dd July 18, 2014
.Dt TTYNAME 3
.Os
.Sh NAME
.Nm ttyname ,
.Nm ttyname_r ,
.Nm isatty
.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 ttyname_r "int fd" "char *buf" "size_t len"
.Ft int
.Fn isatty "int fd"
.Sh DESCRIPTION
These functions operate on file descriptors for terminal type devices.
.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 ttyname
function
returns the name stored in a static buffer which will be overwritten
on subsequent calls.
The
.Fn ttyname_r
function
takes a buffer and length as arguments to avoid this problem.
.Sh RETURN VALUES
The
.Fn isatty
function returns 1 if
.Fa fd
refers to a terminal type device;
otherwise, it returns 0 and may set
.Va errno
to indicate the error.
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.
The
.Fn ttyname_r
function returns 0 if successful.
Otherwise an error number is returned.
.Sh ERRORS
These functions may fail if:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa fd
argument
is not a valid file descriptor.
.It Bq Er ENOTTY
The file associated with
.Fa fd
is not a terminal.
.El
.Pp
Additionally,
.Fn ttyname_r
may fail if:
.Bl -tag -width Er
.It Bq Er ERANGE
The
.Fa bufsize
argument
is smaller than the length of the string to be returned.
.El
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr ptsname 3 ,
.Xr tcgetattr 3 ,
.Xr tty 4 ,
.Xr ttys 5
.Sh HISTORY
The
.Fn isatty
and
.Fn ttyname
functions
appeared in
.At v7 .
The
.Fn ttyname_r
function
appeared in
.Fx 6.0 .
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.
e07eda1a	12	.\" 3. Neither the name of the University nor the names of its contributors
e9ce8d39 A	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	.\"
5b2abdfb	28	.\" @(#)ttyname.3 8.1 (Berkeley) 6/4/93
b061a43b	29	.\" $FreeBSD$
e9ce8d39	30	.\"
b061a43b	31	.Dd July 18, 2014
5b2abdfb	32	.Dt TTYNAME 3
e9ce8d39 A	33	.Os
e9ce8d39 A	34	.Sh NAME
ad3c9f2a	35	.Nm ttyname ,
b061a43b A	36	.Nm ttyname_r ,
b061a43b A	37	.Nm isatty
5b2abdfb	38	.Nd get name of associated terminal (tty) from file descriptor
e9ce8d39 A	39	.Sh LIBRARY
	40	.Lb libc
	41	.Sh SYNOPSIS
5b2abdfb	42	.In unistd.h
ad3c9f2a	43	.Ft char *
b061a43b A	44	.Fn ttyname "int fd"
	45	.Ft int
	46	.Fn ttyname_r "int fd" "char *buf" "size_t len"
5b2abdfb	47	.Ft int
b061a43b	48	.Fn isatty "int fd"
e9ce8d39	49	.Sh DESCRIPTION
b061a43b	50	These functions operate on file descriptors for terminal type devices.
5b2abdfb	51	.Pp
e9ce8d39	52	The
5b2abdfb A	53	.Fn isatty
	54	function
	55	determines if the file descriptor
b061a43b	56	.Fa fd
5b2abdfb A	57	refers to a valid
	58	terminal type device.
	59	.Pp
	60	The
	61	.Fn ttyname
	62	function
	63	gets the related device name of
	64	a file descriptor for which
	65	.Fn isatty
ad3c9f2a	66	is true.
5b2abdfb	67	.Pp
e9ce8d39	68	The
b061a43b	69	.Fn ttyname
5b2abdfb	70	function
b061a43b A	71	returns the name stored in a static buffer which will be overwritten
	72	on subsequent calls.
	73	The
	74	.Fn ttyname_r
	75	function
	76	takes a buffer and length as arguments to avoid this problem.
e9ce8d39	77	.Sh RETURN VALUES
5b2abdfb	78	The
b061a43b A	79	.Fn isatty
	80	function returns 1 if
	81	.Fa fd
	82	refers to a terminal type device;
	83	otherwise, it returns 0 and may set
	84	.Va errno
	85	to indicate the error.
	86	The
5b2abdfb A	87	.Fn ttyname
	88	function
	89	returns the null terminated name if the device is found and
	90	.Fn isatty
b061a43b A	91	is true; otherwise
b061a43b A	92	a
5b2abdfb A	93	.Dv NULL
5b2abdfb A	94	pointer is returned.
b061a43b A	95	The
	96	.Fn ttyname_r
	97	function returns 0 if successful.
	98	Otherwise an error number is returned.
	99	.Sh ERRORS
	100	These functions may fail if:
	101	.Bl -tag -width Er
	102	.It Bq Er EBADF
	103	The
	104	.Fa fd
	105	argument
	106	is not a valid file descriptor.
	107	.It Bq Er ENOTTY
	108	The file associated with
	109	.Fa fd
	110	is not a terminal.
	111	.El
5b2abdfb	112	.Pp
b061a43b A	113	Additionally,
	114	.Fn ttyname_r
	115	may fail if:
	116	.Bl -tag -width Er
	117	.It Bq Er ERANGE
5b2abdfb	118	The
b061a43b A	119	.Fa bufsize
	120	argument
	121	is smaller than the length of the string to be returned.
5b2abdfb	122	.El
e9ce8d39	123	.Sh SEE ALSO
5b2abdfb	124	.Xr ioctl 2 ,
e07eda1a A	125	.Xr ptsname 3 ,
	126	.Xr tcgetattr 3 ,
	127	.Xr tty 4 ,
5b2abdfb	128	.Xr ttys 5
e9ce8d39	129	.Sh HISTORY
b061a43b A	130	The
b061a43b A	131	.Fn isatty
5b2abdfb	132	and
b061a43b A	133	.Fn ttyname
b061a43b A	134	functions
5b2abdfb A	135	appeared in
5b2abdfb A	136	.At v7 .
e9ce8d39	137	The
b061a43b A	138	.Fn ttyname_r
	139	function
	140	appeared in
	141	.Fx 6.0 .