man3/openpty.3

   1 .\" Copyright (c) OpenBSD Group
   2 .\" All rights reserved.
   3 .\"
   4 .\" SPDX-License-Identifier: BSD-3-Clause
   5 .\"
   6 .\" Converted into a manpage again by Martin Schulze <joey@infodrom.org>
   7 .\"
   8 .\" Added -lutil remark, 030718
   9 .\"
  10 .TH openpty 3 (date) "Linux man-pages (unreleased)"
  11 .SH NAME
  12 openpty, login_tty, forkpty \- terminal utility functions
  13 .SH LIBRARY
  14 System utilities library
  15 .RI ( libutil ", " \-lutil )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <pty.h>
  19 .PP
  20 .BI "int openpty(int *" amaster ", int *" aslave ", char *" name ,
  21 .BI "              const struct termios *" termp ,
  22 .BI "              const struct winsize *" winp );
  23 .BI "pid_t forkpty(int *" amaster ", char *" name ,
  24 .BI "              const struct termios *" termp ,
  25 .BI "              const struct winsize *" winp );
  26 .PP
  27 .B #include <utmp.h>
  28 .PP
  29 .BI "int login_tty(int " fd );
  30 .fi
  31 .SH DESCRIPTION
  32 The
  33 .BR openpty ()
  34 function finds an available pseudoterminal and returns file descriptors
  35 for the master and slave in
  36 .I amaster
  37 and
  38 .IR aslave .
  39 If
  40 .I name
  41 is not NULL, the filename of the slave is returned in
  42 .IR name .
  43 If
  44 .I termp
  45 is not NULL, the terminal parameters of the slave will be set to the
  46 values in
  47 .IR termp .
  48 If
  49 .I winp
  50 is not NULL, the window size of the slave will be set to the values in
  51 .IR winp .
  52 .PP
  53 The
  54 .BR login_tty ()
  55 function prepares for a login on the terminal
  56 referred to by the file descriptor
  57 .I fd
  58 (which may be a real terminal device, or the slave of a pseudoterminal as
  59 returned by
  60 .BR openpty ())
  61 by creating a new session, making
  62 .I fd
  63 the controlling terminal for the calling process, setting
  64 .I fd
  65 to be the standard input, output, and error streams of the current
  66 process, and closing
  67 .IR fd .
  68 .PP
  69 The
  70 .BR forkpty ()
  71 function combines
  72 .BR openpty (),
  73 .BR fork (2),
  74 and
  75 .BR login_tty ()
  76 to create a new process operating in a pseudoterminal.
  77 A file descriptor referring to
  78 master side of the pseudoterminal is returned in
  79 .IR amaster .
  80 If
  81 .I name
  82 is not NULL, the buffer it points to is used to return the
  83 filename of the slave.
  84 The
  85 .I termp
  86 and
  87 .I winp
  88 arguments, if not NULL,
  89 will determine the terminal attributes and window size of the slave
  90 side of the pseudoterminal.
  91 .SH RETURN VALUE
  92 If a call to
  93 .BR openpty (),
  94 .BR login_tty (),
  95 or
  96 .BR forkpty ()
  97 is not successful, \-1 is returned and
  98 .I errno
  99 is set to indicate the error.
 100 Otherwise,
 101 .BR openpty (),
 102 .BR login_tty (),
 103 and the child process of
 104 .BR forkpty ()
 105 return 0, and the parent process of
 106 .BR forkpty ()
 107 returns the process ID of the child process.
 108 .SH ERRORS
 109 .BR openpty ()
 110 fails if:
 111 .TP
 112 .B ENOENT
 113 There are no available terminals.
 114 .PP
 115 .BR login_tty ()
 116 fails if
 117 .BR ioctl (2)
 118 fails to set
 119 .I fd
 120 to the controlling terminal of the calling process.
 121 .PP
 122 .BR forkpty ()
 123 fails if either
 124 .BR openpty ()
 125 or
 126 .BR fork (2)
 127 fails.
 128 .SH ATTRIBUTES
 129 For an explanation of the terms used in this section, see
 130 .BR attributes (7).
 131 .ad l
 132 .nh
 133 .TS
 134 allbox;
 135 lbx lb lb
 136 l l l.
 137 Interface       Attribute       Value
 138 T{
 139 .BR forkpty (),
 140 .BR openpty ()
 141 T}      Thread safety   MT-Safe locale
 142 T{
 143 .BR login_tty ()
 144 T}      Thread safety   MT-Unsafe race:ttyname
 145 .TE
 146 .hy
 147 .ad
 148 .sp 1
 149 .SH STANDARDS
 150 These are BSD functions, present in glibc.
 151 They are not standardized in POSIX.
 152 .SH NOTES
 153 The
 154 .B const
 155 modifiers were added to the structure pointer arguments of
 156 .BR openpty ()
 157 and
 158 .BR forkpty ()
 159 in glibc 2.8.
 160 .PP
 161 In versions of glibc before 2.0.92,
 162 .BR openpty ()
 163 returns file descriptors for a BSD pseudoterminal pair;
 164 since glibc 2.0.92,
 165 it first attempts to open a UNIX 98 pseudoterminal pair,
 166 and falls back to opening a BSD pseudoterminal pair if that fails.
 167 .SH BUGS
 168 Nobody knows how much space should be reserved for
 169 .IR name .
 170 So, calling
 171 .BR openpty ()
 172 or
 173 .BR forkpty ()
 174 with non-NULL
 175 .I name
 176 may not be secure.
 177 .SH SEE ALSO
 178 .BR fork (2),
 179 .BR ttyname (3),
 180 .BR pty (7)