LLDB  mainline
Host.h
Go to the documentation of this file.
1 //===-- Host.h --------------------------------------------------*- 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 
9 #ifndef LLDB_HOST_HOST_H
10 #define LLDB_HOST_HOST_H
11 
12 #include "lldb/Host/File.h"
13 #include "lldb/Host/HostThread.h"
15 #include "lldb/Utility/FileSpec.h"
16 #include "lldb/Utility/Timeout.h"
18 #include "lldb/lldb-private.h"
19 #include <cerrno>
20 #include <cstdarg>
21 #include <map>
22 #include <string>
23 #include <type_traits>
24 
25 namespace lldb_private {
26 
27 class FileAction;
28 class ProcessLaunchInfo;
29 class ProcessInstanceInfo;
31 typedef std::vector<ProcessInstanceInfo> ProcessInstanceInfoList;
32 
33 // Exit Type for inferior processes
34 struct WaitStatus {
35  enum Type : uint8_t {
36  Exit, // The status represents the return code from normal
37  // program exit (i.e. WIFEXITED() was true)
38  Signal, // The status represents the signal number that caused
39  // the program to exit (i.e. WIFSIGNALED() was true)
40  Stop, // The status represents the signal number that caused the
41  // program to stop (i.e. WIFSTOPPED() was true)
42  };
43 
45  uint8_t status;
46 
48 
49  static WaitStatus Decode(int wstatus);
50 };
51 
52 inline bool operator==(WaitStatus a, WaitStatus b) {
53  return a.type == b.type && a.status == b.status;
54 }
55 
56 inline bool operator!=(WaitStatus a, WaitStatus b) { return !(a == b); }
57 
58 /// \class Host Host.h "lldb/Host/Host.h"
59 /// A class that provides host computer information.
60 ///
61 /// Host is a class that answers information about the host operating system.
62 class Host {
63 public:
64  typedef std::function<void(lldb::pid_t pid,
65  int signal, // Zero for no signal
66  int status)> // Exit value of process if signal is
67  // zero
69 
70  /// Start monitoring a child process.
71  ///
72  /// Allows easy monitoring of child processes. \a callback will be called
73  /// when the child process exits or if it dies from a signal.
74  ///
75  /// \param[in] callback
76  /// A function callback to call when a child receives a signal
77  /// or exits.
78  ///
79  /// \param[in] pid
80  /// The process ID of a child process to monitor.
81  ///
82  /// \return
83  /// A thread handle that can be used to cancel the thread that
84  /// was spawned to monitor \a pid.
85  static llvm::Expected<HostThread>
87  lldb::pid_t pid);
88 
90 
91  static void SystemLog(SystemLogType type, const char *format, ...)
92  __attribute__((format(printf, 2, 3)));
93 
94  static void SystemLog(SystemLogType type, const char *format, va_list args);
95 
96  /// Get the process ID for the calling process.
97  ///
98  /// \return
99  /// The process ID for the current process.
100  static lldb::pid_t GetCurrentProcessID();
101 
102  static void Kill(lldb::pid_t pid, int signo);
103 
104  /// Get the thread token (the one returned by ThreadCreate when the thread
105  /// was created) for the calling thread in the current process.
106  ///
107  /// \return
108  /// The thread token for the calling thread in the current process.
109  static lldb::thread_t GetCurrentThread();
110 
111  static const char *GetSignalAsCString(int signo);
112 
113  /// Given an address in the current process (the process that is running the
114  /// LLDB code), return the name of the module that it comes from. This can
115  /// be useful when you need to know the path to the shared library that your
116  /// code is running in for loading resources that are relative to your
117  /// binary.
118  ///
119  /// \param[in] host_addr
120  /// The pointer to some code in the current process.
121  ///
122  /// \return
123  /// \b A file spec with the module that contains \a host_addr,
124  /// which may be invalid if \a host_addr doesn't fall into
125  /// any valid module address range.
126  static FileSpec GetModuleFileSpecForHostAddress(const void *host_addr);
127 
128  /// If you have an executable that is in a bundle and want to get back to
129  /// the bundle directory from the path itself, this function will change a
130  /// path to a file within a bundle to the bundle directory itself.
131  ///
132  /// \param[in] file
133  /// A file spec that might point to a file in a bundle.
134  ///
135  /// \param[out] bundle_directory
136  /// An object will be filled in with the bundle directory for
137  /// the bundle when \b true is returned. Otherwise \a file is
138  /// left untouched and \b false is returned.
139  ///
140  /// \return
141  /// \b true if \a file was resolved in \a bundle_directory,
142  /// \b false otherwise.
143  static bool GetBundleDirectory(const FileSpec &file,
144  FileSpec &bundle_directory);
145 
146  /// When executable files may live within a directory, where the directory
147  /// represents an executable bundle (like the MacOSX app bundles), then
148  /// locate the executable within the containing bundle.
149  ///
150  /// \param[in,out] file
151  /// A file spec that currently points to the bundle that will
152  /// be filled in with the executable path within the bundle
153  /// if \b true is returned. Otherwise \a file is left untouched.
154  ///
155  /// \return
156  /// \b true if \a file was resolved, \b false if this function
157  /// was not able to resolve the path.
158  static bool ResolveExecutableInBundle(FileSpec &file);
159 
160  static uint32_t FindProcesses(const ProcessInstanceInfoMatch &match_info,
161  ProcessInstanceInfoList &proc_infos);
162 
163  typedef std::map<lldb::pid_t, bool> TidMap;
164  typedef std::pair<lldb::pid_t, bool> TidPair;
165  static bool FindProcessThreads(const lldb::pid_t pid, TidMap &tids_to_attach);
166 
167  static bool GetProcessInfo(lldb::pid_t pid, ProcessInstanceInfo &proc_info);
168 
169  /// Launch the process specified in launch_info. The monitoring callback in
170  /// launch_info must be set, and it will be called when the process
171  /// terminates.
172  static Status LaunchProcess(ProcessLaunchInfo &launch_info);
173 
174  /// Perform expansion of the command-line for this launch info This can
175  /// potentially involve wildcard expansion
176  /// environment variable replacement, and whatever other
177  /// argument magic the platform defines as part of its typical
178  /// user experience
179  static Status ShellExpandArguments(ProcessLaunchInfo &launch_info);
180 
181  /// Run a shell command.
182  /// \arg command shouldn't be empty
183  /// \arg working_dir Pass empty FileSpec to use the current working directory
184  /// \arg status_ptr Pass NULL if you don't want the process exit status
185  /// \arg signo_ptr Pass NULL if you don't want the signal that caused the
186  /// process to exit
187  /// \arg command_output Pass NULL if you don't want the command output
188  /// \arg hide_stderr if this is false, redirect stderr to stdout
189  static Status RunShellCommand(llvm::StringRef command,
190  const FileSpec &working_dir, int *status_ptr,
191  int *signo_ptr, std::string *command_output,
192  const Timeout<std::micro> &timeout,
193  bool run_in_shell = true,
194  bool hide_stderr = false);
195 
196  /// Run a shell command.
197  /// \arg shell Pass an empty string if you want to use the default shell
198  /// interpreter \arg command \arg working_dir Pass empty FileSpec to use the
199  /// current working directory \arg status_ptr Pass NULL if you don't want
200  /// the process exit status \arg signo_ptr Pass NULL if you don't want the
201  /// signal that caused
202  /// the process to exit
203  /// \arg command_output Pass NULL if you don't want the command output
204  /// \arg hide_stderr If this is \b false, redirect stderr to stdout
205  static Status RunShellCommand(llvm::StringRef shell, llvm::StringRef command,
206  const FileSpec &working_dir, int *status_ptr,
207  int *signo_ptr, std::string *command_output,
208  const Timeout<std::micro> &timeout,
209  bool run_in_shell = true,
210  bool hide_stderr = false);
211 
212  /// Run a shell command.
213  /// \arg working_dir Pass empty FileSpec to use the current working directory
214  /// \arg status_ptr Pass NULL if you don't want the process exit status
215  /// \arg signo_ptr Pass NULL if you don't want the signal that caused the
216  /// process to exit
217  /// \arg command_output Pass NULL if you don't want the command output
218  /// \arg hide_stderr if this is false, redirect stderr to stdout
219  static Status RunShellCommand(const Args &args, const FileSpec &working_dir,
220  int *status_ptr, int *signo_ptr,
221  std::string *command_output,
222  const Timeout<std::micro> &timeout,
223  bool run_in_shell = true,
224  bool hide_stderr = false);
225 
226  /// Run a shell command.
227  /// \arg shell Pass an empty string if you want to use the default
228  /// shell interpreter \arg command \arg working_dir Pass empty FileSpec to use
229  /// the current working directory \arg status_ptr Pass NULL if you don't
230  /// want the process exit status \arg signo_ptr Pass NULL if you don't
231  /// want the signal that caused the
232  /// process to exit
233  /// \arg command_output Pass NULL if you don't want the command output
234  /// \arg hide_stderr If this is \b false, redirect stderr to stdout
235  static Status RunShellCommand(llvm::StringRef shell, const Args &args,
236  const FileSpec &working_dir, int *status_ptr,
237  int *signo_ptr, std::string *command_output,
238  const Timeout<std::micro> &timeout,
239  bool run_in_shell = true,
240  bool hide_stderr = false);
241 
242  static bool OpenFileInExternalEditor(const FileSpec &file_spec,
243  uint32_t line_no);
244 
245  /// Check if we're running in an interactive graphical session.
246  ///
247  /// \return
248  /// True if we're running in an interactive graphical session. False if
249  /// we're not or don't know.
250  static bool IsInteractiveGraphicSession();
251 
252  static Environment GetEnvironment();
253 
254  static std::unique_ptr<Connection>
255  CreateDefaultConnection(llvm::StringRef url);
256 
257 protected:
258  static uint32_t FindProcessesImpl(const ProcessInstanceInfoMatch &match_info,
259  ProcessInstanceInfoList &proc_infos);
260 };
261 
262 } // namespace lldb_private
263 
264 namespace llvm {
265 template <> struct format_provider<lldb_private::WaitStatus> {
266  /// Options = "" gives a human readable description of the status Options =
267  /// "g" gives a gdb-remote protocol status (e.g., X09)
268  static void format(const lldb_private::WaitStatus &WS, raw_ostream &OS,
269  llvm::StringRef Options);
270 };
271 } // namespace llvm
272 
273 #endif // LLDB_HOST_HOST_H
lldb_private::WaitStatus::type
Type type
Definition: Host.h:44
lldb_private::ProcessInstanceInfo
Definition: ProcessInfo.h:108
lldb_private::Host::ResolveExecutableInBundle
static bool ResolveExecutableInBundle(FileSpec &file)
When executable files may live within a directory, where the directory represents an executable bundl...
Definition: common/Host.cpp:351
lldb_private::Connection
Definition: Connection.h:41
lldb_private::Host::FindProcesses
static uint32_t FindProcesses(const ProcessInstanceInfoMatch &match_info, ProcessInstanceInfoList &proc_infos)
Definition: common/Host.cpp:637
llvm
Definition: Debugger.h:50
lldb_private::Host::LaunchProcess
static Status LaunchProcess(ProcessLaunchInfo &launch_info)
Launch the process specified in launch_info.
Definition: common/Host.cpp:547
lldb_private::Host::CreateDefaultConnection
static std::unique_ptr< Connection > CreateDefaultConnection(llvm::StringRef url)
Definition: common/Host.cpp:581
lldb_private::Host
Definition: Host.h:62
lldb_private::Host::GetBundleDirectory
static bool GetBundleDirectory(const FileSpec &file, FileSpec &bundle_directory)
If you have an executable that is in a bundle and want to get back to the bundle directory from the p...
Definition: common/Host.cpp:346
lldb_private::Host::GetSignalAsCString
static const char * GetSignalAsCString(int signo)
Definition: common/Host.cpp:256
lldb_private::WaitStatus::Decode
static WaitStatus Decode(int wstatus)
lldb_private::ProcessInstanceInfoMatch
Definition: ProcessInfo.h:163
lldb_private::Args
Definition: Args.h:33
lldb_private::WaitStatus
Definition: Host.h:34
lldb_private::operator==
bool operator==(const Address &lhs, const Address &rhs)
Definition: Address.cpp:1016
lldb_private::Host::MonitorChildProcessCallback
std::function< void(lldb::pid_t pid, int signal, int status)> MonitorChildProcessCallback
Definition: Host.h:68
lldb_private::FileSpec
Definition: FileSpec.h:56
lldb_private::Host::eSystemLogWarning
@ eSystemLogWarning
Definition: Host.h:89
HostThread.h
lldb::thread_t
pthread_t thread_t
Definition: lldb-types.h:58
lldb-private-forward.h
lldb_private::ProcessLaunchInfo
Definition: ProcessLaunchInfo.h:31
lldb_private::Host::RunShellCommand
static Status RunShellCommand(llvm::StringRef command, const FileSpec &working_dir, int *status_ptr, int *signo_ptr, std::string *command_output, const Timeout< std::micro > &timeout, bool run_in_shell=true, bool hide_stderr=false)
Run a shell command.
Definition: common/Host.cpp:400
lldb_private::Host::IsInteractiveGraphicSession
static bool IsInteractiveGraphicSession()
Check if we're running in an interactive graphical session.
Definition: common/Host.cpp:578
lldb_private::WaitStatus::status
uint8_t status
Definition: Host.h:45
lldb_private::Host::SystemLog
static void SystemLog(SystemLogType type, const char *format,...) __attribute__((format(printf
Definition: common/Host.cpp:230
lldb_private::Host::SystemLogType
SystemLogType
Definition: Host.h:89
lldb_private::Host::FindProcessesImpl
static uint32_t FindProcessesImpl(const ProcessInstanceInfoMatch &match_info, ProcessInstanceInfoList &proc_infos)
Definition: freebsd/Host.cpp:153
lldb_private::Host::TidPair
std::pair< lldb::pid_t, bool > TidPair
Definition: Host.h:164
lldb_private::Host::ShellExpandArguments
static Status ShellExpandArguments(ProcessLaunchInfo &launch_info)
Perform expansion of the command-line for this launch info This can potentially involve wildcard expa...
Definition: freebsd/Host.cpp:246
lldb_private::Host::StartMonitoringChildProcess
static llvm::Expected< HostThread > StartMonitoringChildProcess(const MonitorChildProcessCallback &callback, lldb::pid_t pid)
Start monitoring a child process.
Definition: common/Host.cpp:98
lldb_private::Host::GetCurrentThread
static lldb::thread_t GetCurrentThread()
Get the thread token (the one returned by ThreadCreate when the thread was created) for the calling t...
Definition: common/Host.cpp:252
lldb_private::operator!=
bool operator!=(const Address &lhs, const Address &rhs)
Definition: Address.cpp:1022
lldb-private.h
lldb_private::Host::GetEnvironment
static Environment GetEnvironment()
Definition: freebsd/Host.cpp:244
lldb_private::Status
Definition: Status.h:44
lldb_private::Timeout
Definition: Connection.h:25
uint32_t
lldb::pid_t
uint64_t pid_t
Definition: lldb-types.h:85
lldb_private::Host::GetProcessInfo
static bool GetProcessInfo(lldb::pid_t pid, ProcessInstanceInfo &proc_info)
Definition: freebsd/Host.cpp:230
lldb_private::Environment
Definition: Environment.h:18
Timeout.h
lldb_private::Host::GetCurrentProcessID
static lldb::pid_t GetCurrentProcessID()
Get the process ID for the calling process.
Definition: common/Host.cpp:248
Environment.h
lldb_private::WaitStatus::Signal
@ Signal
Definition: Host.h:38
lldb_private::WaitStatus::WaitStatus
WaitStatus(Type type, uint8_t status)
Definition: Host.h:47
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::Host::OpenFileInExternalEditor
static bool OpenFileInExternalEditor(const FileSpec &file_spec, uint32_t line_no)
Definition: common/Host.cpp:573
FileSpec.h
lldb_private::Host::eSystemLogError
@ eSystemLogError
Definition: Host.h:89
lldb_private::Host::GetModuleFileSpecForHostAddress
static FileSpec GetModuleFileSpecForHostAddress(const void *host_addr)
Given an address in the current process (the process that is running the LLDB code),...
Definition: common/Host.cpp:356
lldb_private::Host::FindProcessThreads
static bool FindProcessThreads(const lldb::pid_t pid, TidMap &tids_to_attach)
Definition: common/Host.cpp:373
lldb_private::Host::Kill
static void Kill(lldb::pid_t pid, int signo)
Definition: common/Host.cpp:568
lldb_private::ProcessInstanceInfoList
std::vector< ProcessInstanceInfo > ProcessInstanceInfoList
Definition: Host.h:30
lldb_private::WaitStatus::Type
Type
Definition: Host.h:35
lldb
Definition: SBAddress.h:15
File.h
lldb_private::WaitStatus::Exit
@ Exit
Definition: Host.h:36
lldb_private::Host::TidMap
std::map< lldb::pid_t, bool > TidMap
Definition: Host.h:163
lldb_private::WaitStatus::Stop
@ Stop
Definition: Host.h:40