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