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  .\"
 37  .Dd April 5, 2008
 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
 63  function allocates a pseudo-tty and returns file descriptors
 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
135  .It Bq Er EAGAIN
136  There are no available pseudo-ttys.
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
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
157  .El
158  .Sh SEE ALSO
159  .Xr fork 2