contrib/llvm/tools/lldb/include/lldb/Host/Host.h

   1 //===-- Host.h --------------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef LLDB_HOST_HOST_H
  11 #define LLDB_HOST_HOST_H
  12
  13 #include "lldb/Host/File.h"
  14 #include "lldb/Host/HostThread.h"
  15 #include "lldb/Utility/FileSpec.h"
  16 #include "lldb/Utility/StringList.h"
  17 #include "lldb/lldb-private-forward.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
  30 //----------------------------------------------------------------------
  31 // Exit Type for inferior processes
  32 //----------------------------------------------------------------------
  33 struct WaitStatus {
  34   enum Type : uint8_t {
  35     Exit,   // The status represents the return code from normal
  36             // program exit (i.e. WIFEXITED() was true)
  37     Signal, // The status represents the signal number that caused
  38             // the program to exit (i.e. WIFSIGNALED() was true)
  39     Stop,   // The status represents the signal number that caused the
  40             // program to stop (i.e. WIFSTOPPED() was true)
  41   };
  42
  43   Type type;
  44   uint8_t status;
  45
  46   WaitStatus(Type type, uint8_t status) : type(type), status(status) {}
  47
  48   static WaitStatus Decode(int wstatus);
  49 };
  50
  51 inline bool operator==(WaitStatus a, WaitStatus b) {
  52   return a.type == b.type && a.status == b.status;
  53 }
  54
  55 inline bool operator!=(WaitStatus a, WaitStatus b) { return !(a == b); }
  56
  57 //----------------------------------------------------------------------
  58 /// @class Host Host.h "lldb/Host/Host.h"
  59 /// @brief A class that provides host computer information.
  60 ///
  61 /// Host is a class that answers information about the host operating
  62 /// system.
  63 //----------------------------------------------------------------------
  64 class Host {
  65 public:
  66   typedef std::function<bool(
  67       lldb::pid_t pid, bool exited,
  68       int signal,  // Zero for no signal
  69       int status)> // Exit value of process if signal is zero
  70       MonitorChildProcessCallback;
  71
  72   //------------------------------------------------------------------
  73   /// Start monitoring a child process.
  74   ///
  75   /// Allows easy monitoring of child processes. \a callback will be
  76   /// called when the child process exits or if it gets a signal. The
  77   /// callback will only be called with signals if \a monitor_signals
  78   /// is \b true. \a callback will usually be called from another
  79   /// thread so the callback function must be thread safe.
  80   ///
  81   /// When the callback gets called, the return value indicates if
  82   /// monitoring should stop. If \b true is returned from \a callback
  83   /// the information will be removed. If \b false is returned then
  84   /// monitoring will continue. If the child process exits, the
  85   /// monitoring will automatically stop after the callback returned
  86   /// regardless of the callback return value.
  87   ///
  88   /// @param[in] callback
  89   ///     A function callback to call when a child receives a signal
  90   ///     (if \a monitor_signals is true) or a child exits.
  91   ///
  92   /// @param[in] pid
  93   ///     The process ID of a child process to monitor, -1 for all
  94   ///     processes.
  95   ///
  96   /// @param[in] monitor_signals
  97   ///     If \b true the callback will get called when the child
  98   ///     process gets a signal. If \b false, the callback will only
  99   ///     get called if the child process exits.
 100   ///
 101   /// @return
 102   ///     A thread handle that can be used to cancel the thread that
 103   ///     was spawned to monitor \a pid.
 104   ///
 105   /// @see static void Host::StopMonitoringChildProcess (uint32_t)
 106   //------------------------------------------------------------------
 107   static HostThread
 108   StartMonitoringChildProcess(const MonitorChildProcessCallback &callback,
 109                               lldb::pid_t pid, bool monitor_signals);
 110
 111   enum SystemLogType { eSystemLogWarning, eSystemLogError };
 112
 113   static void SystemLog(SystemLogType type, const char *format, ...)
 114       __attribute__((format(printf, 2, 3)));
 115
 116   static void SystemLog(SystemLogType type, const char *format, va_list args);
 117
 118   //------------------------------------------------------------------
 119   /// Get the process ID for the calling process.
 120   ///
 121   /// @return
 122   ///     The process ID for the current process.
 123   //------------------------------------------------------------------
 124   static lldb::pid_t GetCurrentProcessID();
 125
 126   static void Kill(lldb::pid_t pid, int signo);
 127
 128   //------------------------------------------------------------------
 129   /// Get the thread token (the one returned by ThreadCreate when the thread was
 130   /// created) for the
 131   /// calling thread in the current process.
 132   ///
 133   /// @return
 134   ///     The thread token for the calling thread in the current process.
 135   //------------------------------------------------------------------
 136   static lldb::thread_t GetCurrentThread();
 137
 138   static const char *GetSignalAsCString(int signo);
 139
 140   //------------------------------------------------------------------
 141   /// Given an address in the current process (the process that
 142   /// is running the LLDB code), return the name of the module that
 143   /// it comes from. This can be useful when you need to know the
 144   /// path to the shared library that your code is running in for
 145   /// loading resources that are relative to your binary.
 146   ///
 147   /// @param[in] host_addr
 148   ///     The pointer to some code in the current process.
 149   ///
 150   /// @return
 151   ///     \b A file spec with the module that contains \a host_addr,
 152   ///     which may be invalid if \a host_addr doesn't fall into
 153   ///     any valid module address range.
 154   //------------------------------------------------------------------
 155   static FileSpec GetModuleFileSpecForHostAddress(const void *host_addr);
 156
 157   //------------------------------------------------------------------
 158   /// If you have an executable that is in a bundle and want to get
 159   /// back to the bundle directory from the path itself, this
 160   /// function will change a path to a file within a bundle to the
 161   /// bundle directory itself.
 162   ///
 163   /// @param[in] file
 164   ///     A file spec that might point to a file in a bundle.
 165   ///
 166   /// @param[out] bundle_directory
 167   ///     An object will be filled in with the bundle directory for
 168   ///     the bundle when \b true is returned. Otherwise \a file is
 169   ///     left untouched and \b false is returned.
 170   ///
 171   /// @return
 172   ///     \b true if \a file was resolved in \a bundle_directory,
 173   ///     \b false otherwise.
 174   //------------------------------------------------------------------
 175   static bool GetBundleDirectory(const FileSpec &file,
 176                                  FileSpec &bundle_directory);
 177
 178   //------------------------------------------------------------------
 179   /// When executable files may live within a directory, where the
 180   /// directory represents an executable bundle (like the MacOSX
 181   /// app bundles), then locate the executable within the containing
 182   /// bundle.
 183   ///
 184   /// @param[in,out] file
 185   ///     A file spec that currently points to the bundle that will
 186   ///     be filled in with the executable path within the bundle
 187   ///     if \b true is returned. Otherwise \a file is left untouched.
 188   ///
 189   /// @return
 190   ///     \b true if \a file was resolved, \b false if this function
 191   ///     was not able to resolve the path.
 192   //------------------------------------------------------------------
 193   static bool ResolveExecutableInBundle(FileSpec &file);
 194
 195   static uint32_t FindProcesses(const ProcessInstanceInfoMatch &match_info,
 196                                 ProcessInstanceInfoList &proc_infos);
 197
 198   typedef std::map<lldb::pid_t, bool> TidMap;
 199   typedef std::pair<lldb::pid_t, bool> TidPair;
 200   static bool FindProcessThreads(const lldb::pid_t pid, TidMap &tids_to_attach);
 201
 202   static bool GetProcessInfo(lldb::pid_t pid, ProcessInstanceInfo &proc_info);
 203
 204   static const lldb::UnixSignalsSP &GetUnixSignals();
 205
 206   static Status LaunchProcess(ProcessLaunchInfo &launch_info);
 207
 208   //------------------------------------------------------------------
 209   /// Perform expansion of the command-line for this launch info
 210   /// This can potentially involve wildcard expansion
 211   //  environment variable replacement, and whatever other
 212   //  argument magic the platform defines as part of its typical
 213   //  user experience
 214   //------------------------------------------------------------------
 215   static Status ShellExpandArguments(ProcessLaunchInfo &launch_info);
 216
 217   // TODO: Convert this function to take a StringRef.
 218   static Status RunShellCommand(
 219       const char *command,         // Shouldn't be NULL
 220       const FileSpec &working_dir, // Pass empty FileSpec to use the current
 221                                    // working directory
 222       int *status_ptr, // Pass NULL if you don't want the process exit status
 223       int *signo_ptr,  // Pass NULL if you don't want the signal that caused the
 224                        // process to exit
 225       std::string
 226           *command_output, // Pass NULL if you don't want the command output
 227       uint32_t timeout_sec,
 228       bool run_in_default_shell = true);
 229
 230   static Status RunShellCommand(
 231       const Args &args,
 232       const FileSpec &working_dir, // Pass empty FileSpec to use the current
 233                                    // working directory
 234       int *status_ptr, // Pass NULL if you don't want the process exit status
 235       int *signo_ptr,  // Pass NULL if you don't want the signal that caused the
 236                        // process to exit
 237       std::string
 238           *command_output, // Pass NULL if you don't want the command output
 239       uint32_t timeout_sec,
 240       bool run_in_default_shell = true);
 241
 242   static bool OpenFileInExternalEditor(const FileSpec &file_spec,
 243                                        uint32_t line_no);
 244
 245   static size_t GetEnvironment(StringList &env);
 246
 247   static std::unique_ptr<Connection>
 248   CreateDefaultConnection(llvm::StringRef url);
 249 };
 250
 251 } // namespace lldb_private
 252
 253 namespace llvm {
 254 template <> struct format_provider<lldb_private::WaitStatus> {
 255   /// Options = "" gives a human readable description of the status
 256   /// Options = "g" gives a gdb-remote protocol status (e.g., X09)
 257   static void format(const lldb_private::WaitStatus &WS, raw_ostream &OS,
 258                      llvm::StringRef Options);
 259 };
 260 } // namespace llvm
 261
 262 #endif // LLDB_HOST_HOST_H