LLDB  mainline
PseudoTerminal.cpp
Go to the documentation of this file.
1 //===-- PseudoTerminal.cpp --------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
10 #include "lldb/Host/Config.h"
11 
12 #include "llvm/Support/Errno.h"
13 
14 #include <stdio.h>
15 #include <stdlib.h>
16 #include <string.h>
17 #if defined(TIOCSCTTY)
18 #include <sys/ioctl.h>
19 #endif
20 
21 #include "lldb/Host/PosixApi.h"
22 
23 #if defined(__ANDROID__)
24 int posix_openpt(int flags);
25 #endif
26 
27 using namespace lldb_private;
28 
29 // Write string describing error number
30 static void ErrnoToStr(char *error_str, size_t error_len) {
31  std::string strerror = llvm::sys::StrError();
32  ::snprintf(error_str, error_len, "%s", strerror.c_str());
33 }
34 
35 // PseudoTerminal constructor
37  : m_master_fd(invalid_fd), m_slave_fd(invalid_fd) {}
38 
39 // Destructor
40 //
41 // The destructor will close the master and slave file descriptors if they are
42 // valid and ownership has not been released using the
43 // ReleaseMasterFileDescriptor() or the ReleaseSaveFileDescriptor() member
44 // functions.
48 }
49 
50 // Close the master file descriptor if it is valid.
52  if (m_master_fd >= 0) {
53  ::close(m_master_fd);
55  }
56 }
57 
58 // Close the slave file descriptor if it is valid.
60  if (m_slave_fd >= 0) {
61  ::close(m_slave_fd);
63  }
64 }
65 
66 // Open the first available pseudo terminal with OFLAG as the permissions. The
67 // file descriptor is stored in this object and can be accessed with the
68 // MasterFileDescriptor() accessor. The ownership of the master file descriptor
69 // can be released using the ReleaseMasterFileDescriptor() accessor. If this
70 // object has a valid master files descriptor when its destructor is called, it
71 // will close the master file descriptor, therefore clients must call
72 // ReleaseMasterFileDescriptor() if they wish to use the master file descriptor
73 // after this object is out of scope or destroyed.
74 //
75 // RETURNS:
76 // True when successful, false indicating an error occurred.
77 bool PseudoTerminal::OpenFirstAvailableMaster(int oflag, char *error_str,
78  size_t error_len) {
79  if (error_str)
80  error_str[0] = '\0';
81 
82 #if !defined(LLDB_DISABLE_POSIX)
83  // Open the master side of a pseudo terminal
84  m_master_fd = ::posix_openpt(oflag);
85  if (m_master_fd < 0) {
86  if (error_str)
87  ErrnoToStr(error_str, error_len);
88  return false;
89  }
90 
91  // Grant access to the slave pseudo terminal
92  if (::grantpt(m_master_fd) < 0) {
93  if (error_str)
94  ErrnoToStr(error_str, error_len);
96  return false;
97  }
98 
99  // Clear the lock flag on the slave pseudo terminal
100  if (::unlockpt(m_master_fd) < 0) {
101  if (error_str)
102  ErrnoToStr(error_str, error_len);
104  return false;
105  }
106 
107  return true;
108 #else
109  if (error_str)
110  ::snprintf(error_str, error_len, "%s", "pseudo terminal not supported");
111  return false;
112 #endif
113 }
114 
115 // Open the slave pseudo terminal for the current master pseudo terminal. A
116 // master pseudo terminal should already be valid prior to calling this
117 // function (see OpenFirstAvailableMaster()). The file descriptor is stored
118 // this object's member variables and can be accessed via the
119 // GetSlaveFileDescriptor(), or released using the ReleaseSlaveFileDescriptor()
120 // member function.
121 //
122 // RETURNS:
123 // True when successful, false indicating an error occurred.
124 bool PseudoTerminal::OpenSlave(int oflag, char *error_str, size_t error_len) {
125  if (error_str)
126  error_str[0] = '\0';
127 
129 
130  // Open the master side of a pseudo terminal
131  const char *slave_name = GetSlaveName(error_str, error_len);
132 
133  if (slave_name == nullptr)
134  return false;
135 
136  m_slave_fd = llvm::sys::RetryAfterSignal(-1, ::open, slave_name, oflag);
137 
138  if (m_slave_fd < 0) {
139  if (error_str)
140  ErrnoToStr(error_str, error_len);
141  return false;
142  }
143 
144  return true;
145 }
146 
147 // Get the name of the slave pseudo terminal. A master pseudo terminal should
148 // already be valid prior to calling this function (see
149 // OpenFirstAvailableMaster()).
150 //
151 // RETURNS:
152 // NULL if no valid master pseudo terminal or if ptsname() fails.
153 // The name of the slave pseudo terminal as a NULL terminated C string
154 // that comes from static memory, so a copy of the string should be
155 // made as subsequent calls can change this value.
156 const char *PseudoTerminal::GetSlaveName(char *error_str,
157  size_t error_len) const {
158  if (error_str)
159  error_str[0] = '\0';
160 
161  if (m_master_fd < 0) {
162  if (error_str)
163  ::snprintf(error_str, error_len, "%s",
164  "master file descriptor is invalid");
165  return nullptr;
166  }
167  const char *slave_name = ::ptsname(m_master_fd);
168 
169  if (error_str && slave_name == nullptr)
170  ErrnoToStr(error_str, error_len);
171 
172  return slave_name;
173 }
174 
175 // Fork a child process and have its stdio routed to a pseudo terminal.
176 //
177 // In the parent process when a valid pid is returned, the master file
178 // descriptor can be used as a read/write access to stdio of the child process.
179 //
180 // In the child process the stdin/stdout/stderr will already be routed to the
181 // slave pseudo terminal and the master file descriptor will be closed as it is
182 // no longer needed by the child process.
183 //
184 // This class will close the file descriptors for the master/slave when the
185 // destructor is called, so be sure to call ReleaseMasterFileDescriptor() or
186 // ReleaseSlaveFileDescriptor() if any file descriptors are going to be used
187 // past the lifespan of this object.
188 //
189 // RETURNS:
190 // in the parent process: the pid of the child, or -1 if fork fails
191 // in the child process: zero
192 lldb::pid_t PseudoTerminal::Fork(char *error_str, size_t error_len) {
193  if (error_str)
194  error_str[0] = '\0';
196 #if !defined(LLDB_DISABLE_POSIX)
197  int flags = O_RDWR;
198  flags |= O_CLOEXEC;
199  if (OpenFirstAvailableMaster(flags, error_str, error_len)) {
200  // Successfully opened our master pseudo terminal
201 
202  pid = ::fork();
203  if (pid < 0) {
204  // Fork failed
205  if (error_str)
206  ErrnoToStr(error_str, error_len);
207  } else if (pid == 0) {
208  // Child Process
209  ::setsid();
210 
211  if (OpenSlave(O_RDWR, error_str, error_len)) {
212  // Successfully opened slave
213 
214  // Master FD should have O_CLOEXEC set, but let's close it just in
215  // case...
217 
218 #if defined(TIOCSCTTY)
219  // Acquire the controlling terminal
220  if (::ioctl(m_slave_fd, TIOCSCTTY, (char *)0) < 0) {
221  if (error_str)
222  ErrnoToStr(error_str, error_len);
223  }
224 #endif
225  // Duplicate all stdio file descriptors to the slave pseudo terminal
226  if (::dup2(m_slave_fd, STDIN_FILENO) != STDIN_FILENO) {
227  if (error_str && !error_str[0])
228  ErrnoToStr(error_str, error_len);
229  }
230 
231  if (::dup2(m_slave_fd, STDOUT_FILENO) != STDOUT_FILENO) {
232  if (error_str && !error_str[0])
233  ErrnoToStr(error_str, error_len);
234  }
235 
236  if (::dup2(m_slave_fd, STDERR_FILENO) != STDERR_FILENO) {
237  if (error_str && !error_str[0])
238  ErrnoToStr(error_str, error_len);
239  }
240  }
241  } else {
242  // Parent Process
243  // Do nothing and let the pid get returned!
244  }
245  }
246 #endif
247  return pid;
248 }
249 
250 // The master file descriptor accessor. This object retains ownership of the
251 // master file descriptor when this accessor is used. Use
252 // ReleaseMasterFileDescriptor() if you wish this object to release ownership
253 // of the master file descriptor.
254 //
255 // Returns the master file descriptor, or -1 if the master file descriptor is
256 // not currently valid.
258 
259 // The slave file descriptor accessor.
260 //
261 // Returns the slave file descriptor, or -1 if the slave file descriptor is not
262 // currently valid.
264 
265 // Release ownership of the master pseudo terminal file descriptor without
266 // closing it. The destructor for this class will close the master file
267 // descriptor if the ownership isn't released using this call and the master
268 // file descriptor has been opened.
270  // Release ownership of the master pseudo terminal file descriptor without
271  // closing it. (the destructor for this class will close it otherwise!)
272  int fd = m_master_fd;
274  return fd;
275 }
276 
277 // Release ownership of the slave pseudo terminal file descriptor without
278 // closing it. The destructor for this class will close the slave file
279 // descriptor if the ownership isn't released using this call and the slave
280 // file descriptor has been opened.
282  // Release ownership of the slave pseudo terminal file descriptor without
283  // closing it (the destructor for this class will close it otherwise!)
284  int fd = m_slave_fd;
286  return fd;
287 }
pid_t setsid(void)
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
void CloseSlaveFileDescriptor()
Close the slave file descriptor if it is valid.
int posix_openpt(int flag)
#define LLDB_INVALID_PROCESS_ID
Definition: lldb-defines.h:92
int m_slave_fd
The file descriptor for the slave.
bool OpenSlave(int oflag, char *error_str, size_t error_len)
Open the slave for the current master pseudo terminal.
const char * GetSlaveName(char *error_str, size_t error_len) const
Get the name of the slave pseudo terminal.
lldb::pid_t Fork(char *error_str, size_t error_len)
Fork a child process that uses pseudo terminals for its stdio.
PseudoTerminal()
Default constructor.
int grantpt(int fd)
int unlockpt(int fd)
int ReleaseMasterFileDescriptor()
Release the master file descriptor.
static void ErrnoToStr(char *error_str, size_t error_len)
void CloseMasterFileDescriptor()
Close the master file descriptor if it is valid.
int GetMasterFileDescriptor() const
The master file descriptor accessor.
bool OpenFirstAvailableMaster(int oflag, char *error_str, size_t error_len)
Open the first available pseudo terminal.
pid_t fork(void)
int GetSlaveFileDescriptor() const
The slave file descriptor accessor.
int ReleaseSlaveFileDescriptor()
Release the slave file descriptor.
Invalid file descriptor value.
char * ptsname(int fd)
uint64_t pid_t
Definition: lldb-types.h:85
int m_master_fd
The file descriptor for the master.