original/man3/openpty.3

   1 .\" Copyright (c) OpenBSD Group
   2 .\" 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 .\" Converted into a manpage again by Martin Schulze <joey@infodrom.org>
  29 .\"
  30 .\" Added -lutil remark, 030718
  31 .\"
  32 .TH OPENPTY 3  2010-06-13 "GNU" "Linux Programmer's Manual"
  33 .SH NAME
  34 openpty, login_tty, forkpty \- tty utility functions
  35 .SH SYNOPSIS
  36 .nf
  37 .B #include <pty.h>
  38 .sp
  39 .BI "int openpty(int *" amaster ", int *" aslave ", char *" name ,
  40 .BI "            const struct termios *" termp ,
  41 .BI "            const struct winsize *" winp );
  42 .sp
  43 .BI "pid_t forkpty(int *" amaster ", char *" name ,
  44 .BI "              const struct termios *" termp ,
  45 .BI "              const struct winsize *" winp );
  46 .sp
  47 .B #include <utmp.h>
  48 .sp
  49 .BI "int login_tty(int " fd );
  50 .sp
  51 Link with \fI\-lutil\fP.
  52 .fi
  53 .SH DESCRIPTION
  54 The
  55 .BR openpty ()
  56 function finds an available pseudo-terminal and returns file descriptors
  57 for the master and slave in
  58 .I amaster
  59 and
  60 .IR aslave .
  61 If
  62 .I name
  63 is not NULL, the filename of the slave is returned in
  64 .IR name .
  65 If
  66 .I termp
  67 is not NULL, the terminal parameters of the slave will be set to the
  68 values in
  69 .IR termp .
  70 If
  71 .I winp
  72 is not NULL, the window size of the slave will be set to the values in
  73 .IR winp .
  74
  75 The
  76 .BR login_tty ()
  77 function prepares for a login on the tty
  78 .I fd
  79 (which may be a real tty device, or the slave of a pseudo-terminal as
  80 returned by
  81 .BR openpty ())
  82 by creating a new session, making
  83 .I fd
  84 the controlling terminal for the calling process, setting
  85 .I fd
  86 to be the standard input, output, and error streams of the current
  87 process, and closing
  88 .IR fd .
  89
  90 The
  91 .BR forkpty ()
  92 function combines
  93 .BR openpty (),
  94 .BR fork (2),
  95 and
  96 .BR login_tty ()
  97 to create a new process operating in a pseudo-terminal.
  98 The file
  99 descriptor of the master side of the pseudo-terminal is returned in
 100 .IR amaster ,
 101 and the filename of the slave in
 102 .I name
 103 if it is not NULL.
 104 The
 105 .I termp
 106 and
 107 .I winp
 108 arguments, if not NULL,
 109 will determine the terminal attributes and window size of the slave
 110 side of the pseudo-terminal.
 111 .SH "RETURN VALUE"
 112 If a call to
 113 .BR openpty (),
 114 .BR login_tty (),
 115 or
 116 .BR forkpty ()
 117 is not successful, \-1 is returned and
 118 .I errno
 119 is set to indicate the error.
 120 Otherwise,
 121 .BR openpty (),
 122 .BR login_tty (),
 123 and the child process of
 124 .BR forkpty ()
 125 return 0, and the parent process of
 126 .BR forkpty ()
 127 returns the process ID of the child process.
 128 .SH ERRORS
 129 .BR openpty ()
 130 will fail if:
 131 .TP
 132 .B ENOENT
 133 There are no available ttys.
 134 .LP
 135 .BR login_tty ()
 136 will fail if
 137 .BR ioctl (2)
 138 fails to set
 139 .I fd
 140 to the controlling terminal of the calling process.
 141 .LP
 142 .BR forkpty ()
 143 will fail if either
 144 .BR openpty ()
 145 or
 146 .BR fork (2)
 147 fails.
 148 .SH "CONFORMING TO"
 149 These are BSD functions, present in libc5 and glibc2.
 150 They are not standardized in POSIX.
 151 .SH NOTES
 152 The
 153 .B const
 154 modifiers were added to the structure pointer arguments of
 155 .BR openpty ()
 156 and
 157 .BR forkpty ()
 158 in glibc 2.8.
 159
 160 In versions of glibc before 2.0.92,
 161 .BR openpty ()
 162 returns file descriptors for a BSD pseudo-terminal pair;
 163 since glibc 2.0.92,
 164 it first attempts to open a Unix 98 pseudo-terminal pair,
 165 and falls back to opening a BSD pseudo-terminal pair if that fails.
 166 .SH BUGS
 167 Nobody knows how much space should be reserved for
 168 .IR name .
 169 So, calling
 170 .BR openpty ()
 171 or
 172 .BR forkpty ()
 173 with non-NULL
 174 .I name
 175 may not be secure.
 176 .SH "SEE ALSO"
 177 .BR fork (2),
 178 .BR ttyname (3),
 179 .BR pty (7)