original/man3/openpty.3

   1 .\" Copyright (c) OpenBSD Group
   2 .\" All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_3_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. Neither the name of the University nor the names of its contributors
  14 .\"    may be used to endorse or promote products derived from this software
  15 .\"    without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\" %%%LICENSE_END
  29 .\"
  30 .\" Converted into a manpage again by Martin Schulze <joey@infodrom.org>
  31 .\"
  32 .\" Added -lutil remark, 030718
  33 .\"
  34 .TH OPENPTY 3  2010-06-13 "GNU" "Linux Programmer's Manual"
  35 .SH NAME
  36 openpty, login_tty, forkpty \- terminal utility functions
  37 .SH SYNOPSIS
  38 .nf
  39 .B #include <pty.h>
  40 .sp
  41 .BI "int openpty(int *" amaster ", int *" aslave ", char *" name ,
  42 .BI "            const struct termios *" termp ,
  43 .BI "            const struct winsize *" winp );
  44 .sp
  45 .BI "pid_t forkpty(int *" amaster ", char *" name ,
  46 .BI "              const struct termios *" termp ,
  47 .BI "              const struct winsize *" winp );
  48 .sp
  49 .B #include <utmp.h>
  50 .sp
  51 .BI "int login_tty(int " fd );
  52 .sp
  53 Link with \fI\-lutil\fP.
  54 .fi
  55 .SH DESCRIPTION
  56 The
  57 .BR openpty ()
  58 function finds an available pseudoterminal and returns file descriptors
  59 for the master and slave in
  60 .I amaster
  61 and
  62 .IR aslave .
  63 If
  64 .I name
  65 is not NULL, the filename of the slave is returned in
  66 .IR name .
  67 If
  68 .I termp
  69 is not NULL, the terminal parameters of the slave will be set to the
  70 values in
  71 .IR termp .
  72 If
  73 .I winp
  74 is not NULL, the window size of the slave will be set to the values in
  75 .IR winp .
  76
  77 The
  78 .BR login_tty ()
  79 function prepares for a login on the terminal
  80 .I fd
  81 (which may be a real terminal device, or the slave of a pseudoterminal as
  82 returned by
  83 .BR openpty ())
  84 by creating a new session, making
  85 .I fd
  86 the controlling terminal for the calling process, setting
  87 .I fd
  88 to be the standard input, output, and error streams of the current
  89 process, and closing
  90 .IR fd .
  91
  92 The
  93 .BR forkpty ()
  94 function combines
  95 .BR openpty (),
  96 .BR fork (2),
  97 and
  98 .BR login_tty ()
  99 to create a new process operating in a pseudoterminal.
 100 The file
 101 descriptor of the master side of the pseudoterminal is returned in
 102 .IR amaster ,
 103 and the filename of the slave in
 104 .I name
 105 if it is not NULL.
 106 The
 107 .I termp
 108 and
 109 .I winp
 110 arguments, if not NULL,
 111 will determine the terminal attributes and window size of the slave
 112 side of the pseudoterminal.
 113 .SH RETURN VALUE
 114 If a call to
 115 .BR openpty (),
 116 .BR login_tty (),
 117 or
 118 .BR forkpty ()
 119 is not successful, \-1 is returned and
 120 .I errno
 121 is set to indicate the error.
 122 Otherwise,
 123 .BR openpty (),
 124 .BR login_tty (),
 125 and the child process of
 126 .BR forkpty ()
 127 return 0, and the parent process of
 128 .BR forkpty ()
 129 returns the process ID of the child process.
 130 .SH ERRORS
 131 .BR openpty ()
 132 will fail if:
 133 .TP
 134 .B ENOENT
 135 There are no available terminals.
 136 .LP
 137 .BR login_tty ()
 138 will fail if
 139 .BR ioctl (2)
 140 fails to set
 141 .I fd
 142 to the controlling terminal of the calling process.
 143 .LP
 144 .BR forkpty ()
 145 will fail if either
 146 .BR openpty ()
 147 or
 148 .BR fork (2)
 149 fails.
 150 .SH CONFORMING TO
 151 These are BSD functions, present in libc5 and glibc2.
 152 They are not standardized in POSIX.
 153 .SH NOTES
 154 The
 155 .B const
 156 modifiers were added to the structure pointer arguments of
 157 .BR openpty ()
 158 and
 159 .BR forkpty ()
 160 in glibc 2.8.
 161
 162 In versions of glibc before 2.0.92,
 163 .BR openpty ()
 164 returns file descriptors for a BSD pseudoterminal pair;
 165 since glibc 2.0.92,
 166 it first attempts to open a UNIX 98 pseudoterminal pair,
 167 and falls back to opening a BSD pseudoterminal pair if that fails.
 168 .SH BUGS
 169 Nobody knows how much space should be reserved for
 170 .IR name .
 171 So, calling
 172 .BR openpty ()
 173 or
 174 .BR forkpty ()
 175 with non-NULL
 176 .I name
 177 may not be secure.
 178 .SH SEE ALSO
 179 .BR fork (2),
 180 .BR ttyname (3),
 181 .BR pty (7)
 182 .SH COLOPHON
 183 This page is part of release 3.67 of the Linux
 184 .I man-pages
 185 project.
 186 A description of the project,
 187 information about reporting bugs,
 188 and the latest version of this page,
 189 can be found at
 190 \%http://www.kernel.org/doc/man\-pages/.