git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

Commit	Line	Data
	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$
	30	.\"
	31	.Dd July 18, 2014
	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 file descriptors for terminal type devices.
	51	.Pp
	52	The
	53	.Fn isatty
	54	function
	55	determines if the file descriptor
	56	.Fa fd
	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
	66	is true.
	67	.Pp
	68	The
	69	.Fn ttyname
	70	function
	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.
	77	.Sh RETURN VALUES
	78	The
	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
	87	.Fn ttyname
	88	function
	89	returns the null terminated name if the device is found and
	90	.Fn isatty
	91	is true; otherwise
	92	a
	93	.Dv NULL
	94	pointer is returned.
	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
	112	.Pp
	113	Additionally,
	114	.Fn ttyname_r
	115	may fail if:
	116	.Bl -tag -width Er
	117	.It Bq Er ERANGE
	118	The
	119	.Fa bufsize
	120	argument
	121	is smaller than the length of the string to be returned.
	122	.El
	123	.Sh SEE ALSO
	124	.Xr ioctl 2 ,
	125	.Xr ptsname 3 ,
	126	.Xr tcgetattr 3 ,
	127	.Xr tty 4 ,
	128	.Xr ttys 5
	129	.Sh HISTORY
	130	The
	131	.Fn isatty
	132	and
	133	.Fn ttyname
	134	functions
	135	appeared in
	136	.At v7 .
	137	The
	138	.Fn ttyname_r
	139	function
	140	appeared in
	141	.Fx 6.0 .