[apple/libc.git] / util / openpty.3

.\"	$OpenBSD: openpty.3,v 1.3 1996/11/24 23:53:12 millert Exp $
.\" Copyright (c) 1995
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software developed by the Computer Systems
.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
.\" BG 91-66 and contributed to Berkeley.
.\"
.\" 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.
.\"
.Dd April 5, 2008
.Dt OPENPTY 3
.Os
.Sh NAME
.Nm openpty ,
.Nm login_tty ,
.Nm forkpty
.Nd tty utility functions
.Sh SYNOPSIS
.Fd #include <util.h>
.Ft int
.Fn openpty "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp"
.Ft int
.Fn login_tty "int fd"
.Ft pid_t
.Fn forkpty "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp"
.Sh DESCRIPTION
The
.Fn openpty ,
.Fn login_tty ,
and
.Fn forkpty
functions perform manipulations on ttys and pseudo-ttys.
.Pp
The
.Fn openpty
function allocates a pseudo-tty and returns file descriptors
for the master and slave in
.Fa amaster
and
.Fa aslave .
If
.Fa name
is non-null, the filename of the slave is returned in
.Fa name .
If
.Fa termp
is non-null, the terminal parameters of the slave will be set to the
values in
.Fa termp .
If
.Fa winp
is non-null, the window size of the slave will be set to the values in
.Fa winp .
.Pp
The
.Fn login_tty
function prepares for a login on the tty
.Fa fd
(which may be a real tty device, or the slave of a pseudo-tty as
returned by
.Fn openpty )
by creating a new session, making
.Fa fd
the controlling terminal for the current process, setting
.Fa fd
to be the standard input, output, and error streams of the current
process, and closing
.Fa fd .
.Pp
The
.Fn forkpty
function combines
.Fn openpty ,
.Fn fork ,
and
.Fn login_tty
to creates a new process operating in a pseudo-tty.  The file
descriptor of the master side of the pseudo-tty is returned in
.Fa amaster ,
and the filename of the slave in
.Fa name
if it is non-null.  The
.Fa termp
and
.Fa winp
parameters, if non-null, will determine the terminal attributes and
window size of the slave side of the pseudo-tty.
.Sh RETURN VALUES
If a call to
.Fn openpty ,
.Fn login_tty ,
or
.Fn forkpty
is not successful, -1 is returned and
.Va errno
is set to indicate the error.  Otherwise,
.Fn openpty ,
.Fn login_tty ,
and the child process of
.Fn forkpty
return 0, and the parent process of
.Fn forkpty
returns the process ID of the child process.
.Sh ERRORS
.Fn openpty
will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
There are no available pseudo-ttys.
.El
.Pp
.Fn login_tty
will fail if
.Fn ioctl
fails to set
.Fa fd
to the controlling terminal of the current process.
.Fn forkpty
will fail if either
.Fn openpty
or
.Fn fork
fails.
.Sh FILES
.Bl -tag -width /dev/ttys[0-9][0-9][0-9] -compact
.It Pa /dev/ptmx
cloning pseudo-tty device
.It Pa /dev/ttys[0-9][0-9][0-9]
slave pseudo-tty devices
.El
.Sh SEE ALSO
.Xr fork 2
Commit	Line	Data
224c7076 A	1	.\" $OpenBSD: openpty.3,v 1.3 1996/11/24 23:53:12 millert Exp $
	2	.\" Copyright (c) 1995
	3	.\" The Regents of the University of California. All rights reserved.
	4	.\"
	5	.\" This code is derived from software developed by the Computer Systems
	6	.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
	7	.\" BG 91-66 and contributed to Berkeley.
	8	.\"
	9	.\" Redistribution and use in source and binary forms, with or without
	10	.\" modification, are permitted provided that the following conditions
	11	.\" are met:
	12	.\" 1. Redistributions of source code must retain the above copyright
	13	.\" notice, this list of conditions and the following disclaimer.
	14	.\" 2. Redistributions in binary form must reproduce the above copyright
	15	.\" notice, this list of conditions and the following disclaimer in the
	16	.\" documentation and/or other materials provided with the distribution.
	17	.\" 3. All advertising materials mentioning features or use of this software
	18	.\" must display the following acknowledgement:
	19	.\" This product includes software developed by the University of
	20	.\" California, Berkeley and its contributors.
	21	.\" 4. Neither the name of the University nor the names of its contributors
	22	.\" may be used to endorse or promote products derived from this software
	23	.\" without specific prior written permission.
	24	.\"
	25	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	26	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	27	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	28	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	29	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	30	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	31	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	32	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	33	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	34	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	35	.\" SUCH DAMAGE.
	36	.\"
34e8f829	37	.Dd April 5, 2008
224c7076 A	38	.Dt OPENPTY 3
	39	.Os
	40	.Sh NAME
	41	.Nm openpty ,
	42	.Nm login_tty ,
	43	.Nm forkpty
	44	.Nd tty utility functions
	45	.Sh SYNOPSIS
	46	.Fd #include <util.h>
	47	.Ft int
	48	.Fn openpty "int amaster" "int aslave" "char name" "struct termios termp" "struct winsize *winp"
	49	.Ft int
	50	.Fn login_tty "int fd"
	51	.Ft pid_t
	52	.Fn forkpty "int amaster" "char name" "struct termios termp" "struct winsize winp"
	53	.Sh DESCRIPTION
	54	The
	55	.Fn openpty ,
	56	.Fn login_tty ,
	57	and
	58	.Fn forkpty
	59	functions perform manipulations on ttys and pseudo-ttys.
	60	.Pp
	61	The
	62	.Fn openpty
34e8f829	63	function allocates a pseudo-tty and returns file descriptors
224c7076 A	64	for the master and slave in
	65	.Fa amaster
	66	and
	67	.Fa aslave .
	68	If
	69	.Fa name
	70	is non-null, the filename of the slave is returned in
	71	.Fa name .
	72	If
	73	.Fa termp
	74	is non-null, the terminal parameters of the slave will be set to the
	75	values in
	76	.Fa termp .
	77	If
	78	.Fa winp
	79	is non-null, the window size of the slave will be set to the values in
	80	.Fa winp .
	81	.Pp
	82	The
	83	.Fn login_tty
	84	function prepares for a login on the tty
	85	.Fa fd
	86	(which may be a real tty device, or the slave of a pseudo-tty as
	87	returned by
	88	.Fn openpty )
	89	by creating a new session, making
	90	.Fa fd
	91	the controlling terminal for the current process, setting
	92	.Fa fd
	93	to be the standard input, output, and error streams of the current
	94	process, and closing
	95	.Fa fd .
	96	.Pp
	97	The
	98	.Fn forkpty
	99	function combines
	100	.Fn openpty ,
	101	.Fn fork ,
	102	and
	103	.Fn login_tty
	104	to creates a new process operating in a pseudo-tty. The file
	105	descriptor of the master side of the pseudo-tty is returned in
	106	.Fa amaster ,
	107	and the filename of the slave in
	108	.Fa name
	109	if it is non-null. The
	110	.Fa termp
	111	and
	112	.Fa winp
	113	parameters, if non-null, will determine the terminal attributes and
	114	window size of the slave side of the pseudo-tty.
	115	.Sh RETURN VALUES
	116	If a call to
	117	.Fn openpty ,
	118	.Fn login_tty ,
	119	or
	120	.Fn forkpty
	121	is not successful, -1 is returned and
	122	.Va errno
	123	is set to indicate the error. Otherwise,
	124	.Fn openpty ,
	125	.Fn login_tty ,
	126	and the child process of
	127	.Fn forkpty
128	return 0, and the parent process of
129	.Fn forkpty
130	returns the process ID of the child process.
131	.Sh ERRORS
132	.Fn openpty
133	will fail if:
134	.Bl -tag -width Er
34e8f829 A	135	.It Bq Er EAGAIN
34e8f829 A	136	There are no available pseudo-ttys.
224c7076 A	137	.El
	138	.Pp
	139	.Fn login_tty
	140	will fail if
	141	.Fn ioctl
	142	fails to set
	143	.Fa fd
	144	to the controlling terminal of the current process.
	145	.Fn forkpty
	146	will fail if either
	147	.Fn openpty
	148	or
	149	.Fn fork
	150	fails.
	151	.Sh FILES
34e8f829 A	152	.Bl -tag -width /dev/ttys[0-9][0-9][0-9] -compact
	153	.It Pa /dev/ptmx
	154	cloning pseudo-tty device
	155	.It Pa /dev/ttys[0-9][0-9][0-9]
	156	slave pseudo-tty devices
224c7076 A	157	.El
	158	.Sh SEE ALSO
	159	.Xr fork 2