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 <map>
21 #include <stdarg.h>
22 #include <string>
23 #include <type_traits>
24 
25 namespace lldb_private {
26 
27 class FileAction;
28 class ProcessLaunchInfo;
29 class ProcessInstanceInfo;
30 class ProcessInstanceInfoList;
31 class ProcessInstanceInfoMatch;
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 
47  WaitStatus(Type type, uint8_t status) : type(type), status(status) {}
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<bool(
65  lldb::pid_t pid, bool exited,
66  int signal, // Zero for no signal
67  int status)> // Exit value of process if signal is 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 gets a signal. The callback will
74  /// only be called with signals if \a monitor_signals is \b true. \a
75  /// callback will usually be called from another thread so the callback
76  /// function must be thread safe.
77  ///
78  /// When the callback gets called, the return value indicates if monitoring
79  /// should stop. If \b true is returned from \a callback the information
80  /// will be removed. If \b false is returned then monitoring will continue.
81  /// If the child process exits, the monitoring will automatically stop after
82  /// the callback returned regardless of the callback return value.
83  ///
84  /// \param[in] callback
85  /// A function callback to call when a child receives a signal
86  /// (if \a monitor_signals is true) or a child exits.
87  ///
88  /// \param[in] pid
89  /// The process ID of a child process to monitor, -1 for all
90  /// processes.
91  ///
92  /// \param[in] monitor_signals
93  /// If \b true the callback will get called when the child
94  /// process gets a signal. If \b false, the callback will only
95  /// get called if the child process exits.
96  ///
97  /// \return
98  /// A thread handle that can be used to cancel the thread that
99  /// was spawned to monitor \a pid.
100  ///
101  /// \see static void Host::StopMonitoringChildProcess (uint32_t)
102  static HostThread
103  StartMonitoringChildProcess(const MonitorChildProcessCallback &callback,
104  lldb::pid_t pid, bool monitor_signals);
105 
106  enum SystemLogType { eSystemLogWarning, eSystemLogError };
107 
108  static void SystemLog(SystemLogType type, const char *format, ...)
109  __attribute__((format(printf, 2, 3)));
110 
111  static void SystemLog(SystemLogType type, const char *format, va_list args);
112 
113  /// Get the process ID for the calling process.
114  ///
115  /// \return
116  /// The process ID for the current process.
117  static lldb::pid_t GetCurrentProcessID();
118 
119  static void Kill(lldb::pid_t pid, int signo);
120 
121  /// Get the thread token (the one returned by ThreadCreate when the thread
122  /// was created) for the calling thread in the current process.
123  ///
124  /// \return
125  /// The thread token for the calling thread in the current process.
126  static lldb::thread_t GetCurrentThread();
127 
128  static const char *GetSignalAsCString(int signo);
129 
130  /// Given an address in the current process (the process that is running the
131  /// LLDB code), return the name of the module that it comes from. This can
132  /// be useful when you need to know the path to the shared library that your
133  /// code is running in for loading resources that are relative to your
134  /// binary.
135  ///
136  /// \param[in] host_addr
137  /// The pointer to some code in the current process.
138  ///
139  /// \return
140  /// \b A file spec with the module that contains \a host_addr,
141  /// which may be invalid if \a host_addr doesn't fall into
142  /// any valid module address range.
143  static FileSpec GetModuleFileSpecForHostAddress(const void *host_addr);
144 
145  /// If you have an executable that is in a bundle and want to get back to
146  /// the bundle directory from the path itself, this function will change a
147  /// path to a file within a bundle to the bundle directory itself.
148  ///
149  /// \param[in] file
150  /// A file spec that might point to a file in a bundle.
151  ///
152  /// \param[out] bundle_directory
153  /// An object will be filled in with the bundle directory for
154  /// the bundle when \b true is returned. Otherwise \a file is
155  /// left untouched and \b false is returned.
156  ///
157  /// \return
158  /// \b true if \a file was resolved in \a bundle_directory,
159  /// \b false otherwise.
160  static bool GetBundleDirectory(const FileSpec &file,
161  FileSpec &bundle_directory);
162 
163  /// When executable files may live within a directory, where the directory
164  /// represents an executable bundle (like the MacOSX app bundles), then
165  /// locate the executable within the containing bundle.
166  ///
167  /// \param[in,out] file
168  /// A file spec that currently points to the bundle that will
169  /// be filled in with the executable path within the bundle
170  /// if \b true is returned. Otherwise \a file is left untouched.
171  ///
172  /// \return
173  /// \b true if \a file was resolved, \b false if this function
174  /// was not able to resolve the path.
175  static bool ResolveExecutableInBundle(FileSpec &file);
176 
177  static uint32_t FindProcesses(const ProcessInstanceInfoMatch &match_info,
178  ProcessInstanceInfoList &proc_infos);
179 
180  typedef std::map<lldb::pid_t, bool> TidMap;
181  typedef std::pair<lldb::pid_t, bool> TidPair;
182  static bool FindProcessThreads(const lldb::pid_t pid, TidMap &tids_to_attach);
183 
184  static bool GetProcessInfo(lldb::pid_t pid, ProcessInstanceInfo &proc_info);
185 
186  /// Launch the process specified in launch_info. The monitoring callback in
187  /// launch_info must be set, and it will be called when the process
188  /// terminates.
189  static Status LaunchProcess(ProcessLaunchInfo &launch_info);
190 
191  /// Perform expansion of the command-line for this launch info This can
192  /// potentially involve wildcard expansion
193  /// environment variable replacement, and whatever other
194  /// argument magic the platform defines as part of its typical
195  /// user experience
196  static Status ShellExpandArguments(ProcessLaunchInfo &launch_info);
197 
198  /// Run a shell command.
199  /// \arg command shouldn't be NULL
200  /// \arg working_dir Pass empty FileSpec to use the current working directory
201  /// \arg status_ptr Pass NULL if you don't want the process exit status
202  /// \arg signo_ptr Pass NULL if you don't want the signal that caused the
203  /// process to exit
204  /// \arg command_output Pass NULL if you don't want the command output
205  /// \arg hide_stderr if this is false, redirect stderr to stdout
206  /// TODO: Convert this function to take a StringRef.
207  static Status RunShellCommand(const char *command,
208  const FileSpec &working_dir, int *status_ptr,
209  int *signo_ptr, std::string *command_output,
210  const Timeout<std::micro> &timeout,
211  bool run_in_default_shell = true,
212  bool hide_stderr = false);
213 
214  /// Run a shell command.
215  /// \arg working_dir Pass empty FileSpec to use the current working directory
216  /// \arg status_ptr Pass NULL if you don't want the process exit status
217  /// \arg signo_ptr Pass NULL if you don't want the signal that caused the
218  /// process to exit
219  /// \arg command_output Pass NULL if you don't want the command output
220  /// \arg hide_stderr if this is false, redirect stderr to stdout
221  static Status RunShellCommand(const Args &args, const FileSpec &working_dir,
222  int *status_ptr, int *signo_ptr,
223  std::string *command_output,
224  const Timeout<std::micro> &timeout,
225  bool run_in_default_shell = true,
226  bool hide_stderr = false);
227 
228  static bool OpenFileInExternalEditor(const FileSpec &file_spec,
229  uint32_t line_no);
230 
231  static Environment GetEnvironment();
232 
233  static std::unique_ptr<Connection>
234  CreateDefaultConnection(llvm::StringRef url);
235 };
236 
237 } // namespace lldb_private
238 
239 namespace llvm {
240 template <> struct format_provider<lldb_private::WaitStatus> {
241  /// Options = "" gives a human readable description of the status Options =
242  /// "g" gives a gdb-remote protocol status (e.g., X09)
243  static void format(const lldb_private::WaitStatus &WS, raw_ostream &OS,
244  llvm::StringRef Options);
245 };
246 } // namespace llvm
247 
248 #endif // LLDB_HOST_HOST_H
A command line argument class.
Definition: Args.h:32
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
Definition: Debugger.h:71
A file utility class.
Definition: FileSpec.h:55
WaitStatus(Type type, uint8_t status)
Definition: Host.h:47
bool operator==(const Address &lhs, const Address &rhs)
Definition: Address.cpp:973
std::pair< lldb::pid_t, bool > TidPair
Definition: Host.h:181
bool operator!=(const Address &lhs, const Address &rhs)
Definition: Address.cpp:979
pthread_t thread_t
Definition: lldb-types.h:58
uint64_t pid_t
Definition: lldb-types.h:85
std::map< lldb::pid_t, bool > TidMap
Definition: Host.h:180
std::function< bool(lldb::pid_t pid, bool exited, int signal, int status)> MonitorChildProcessCallback
Definition: Host.h:68
static WaitStatus Decode(int wstatus)
An error handling class.
Definition: Status.h:44
A class that provides host computer information.
Definition: Host.h:62