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 liblldb_Host_h_ 11 #define liblldb_Host_h_ 12 #if defined(__cplusplus) 13 14 #include <stdarg.h> 15 16 #include <map> 17 #include <string> 18 19 #include "lldb/lldb-private.h" 20 #include "lldb/lldb-private-forward.h" 21 #include "lldb/Core/StringList.h" 22 #include "lldb/Host/File.h" 23 #include "lldb/Host/FileSpec.h" 24 #include "lldb/Host/HostThread.h" 25 26 namespace lldb_private { 27 28 class FileAction; 29 class ProcessLaunchInfo; 30 31 //---------------------------------------------------------------------- 32 /// @class Host Host.h "lldb/Host/Host.h" 33 /// @brief A class that provides host computer information. 34 /// 35 /// Host is a class that answers information about the host operating 36 /// system. 37 //---------------------------------------------------------------------- 38 class Host 39 { 40 public: 41 42 typedef bool (*MonitorChildProcessCallback) (void *callback_baton, 43 lldb::pid_t pid, 44 bool exited, 45 int signal, // Zero for no signal 46 int status); // Exit value of process if signal is zero 47 48 //------------------------------------------------------------------ 49 /// Start monitoring a child process. 50 /// 51 /// Allows easy monitoring of child processes. \a callback will be 52 /// called when the child process exits or if it gets a signal. The 53 /// callback will only be called with signals if \a monitor_signals 54 /// is \b true. \a callback will usually be called from another 55 /// thread so the callback function must be thread safe. 56 /// 57 /// When the callback gets called, the return value indicates if 58 /// monitoring should stop. If \b true is returned from \a callback 59 /// the information will be removed. If \b false is returned then 60 /// monitoring will continue. If the child process exits, the 61 /// monitoring will automatically stop after the callback returned 62 /// regardless of the callback return value. 63 /// 64 /// @param[in] callback 65 /// A function callback to call when a child receives a signal 66 /// (if \a monitor_signals is true) or a child exits. 67 /// 68 /// @param[in] callback_baton 69 /// A void * of user data that will be pass back when 70 /// \a callback is called. 71 /// 72 /// @param[in] pid 73 /// The process ID of a child process to monitor, -1 for all 74 /// processes. 75 /// 76 /// @param[in] monitor_signals 77 /// If \b true the callback will get called when the child 78 /// process gets a signal. If \b false, the callback will only 79 /// get called if the child process exits. 80 /// 81 /// @return 82 /// A thread handle that can be used to cancel the thread that 83 /// was spawned to monitor \a pid. 84 /// 85 /// @see static void Host::StopMonitoringChildProcess (uint32_t) 86 //------------------------------------------------------------------ 87 static HostThread StartMonitoringChildProcess(MonitorChildProcessCallback callback, void *callback_baton, lldb::pid_t pid, 88 bool monitor_signals); 89 90 enum SystemLogType 91 { 92 eSystemLogWarning, 93 eSystemLogError 94 }; 95 96 static void 97 SystemLog (SystemLogType type, const char *format, ...) __attribute__ ((format (printf, 2, 3))); 98 99 static void 100 SystemLog (SystemLogType type, const char *format, va_list args); 101 102 //------------------------------------------------------------------ 103 /// Get the process ID for the calling process. 104 /// 105 /// @return 106 /// The process ID for the current process. 107 //------------------------------------------------------------------ 108 static lldb::pid_t 109 GetCurrentProcessID (); 110 111 static void 112 Kill(lldb::pid_t pid, int signo); 113 114 //------------------------------------------------------------------ 115 /// Get the thread ID for the calling thread in the current process. 116 /// 117 /// @return 118 /// The thread ID for the calling thread in the current process. 119 //------------------------------------------------------------------ 120 static lldb::tid_t 121 GetCurrentThreadID (); 122 123 //------------------------------------------------------------------ 124 /// Get the thread token (the one returned by ThreadCreate when the thread was 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 131 GetCurrentThread (); 132 133 static const char * 134 GetSignalAsCString (int signo); 135 136 typedef void (*ThreadLocalStorageCleanupCallback) (void *p); 137 138 static lldb::thread_key_t 139 ThreadLocalStorageCreate(ThreadLocalStorageCleanupCallback callback); 140 141 static void* 142 ThreadLocalStorageGet(lldb::thread_key_t key); 143 144 static void 145 ThreadLocalStorageSet(lldb::thread_key_t key, void *value); 146 147 148 //------------------------------------------------------------------ 149 /// Given an address in the current process (the process that 150 /// is running the LLDB code), return the name of the module that 151 /// it comes from. This can be useful when you need to know the 152 /// path to the shared library that your code is running in for 153 /// loading resources that are relative to your binary. 154 /// 155 /// @param[in] host_addr 156 /// The pointer to some code in the current process. 157 /// 158 /// @return 159 /// \b A file spec with the module that contains \a host_addr, 160 /// which may be invalid if \a host_addr doesn't fall into 161 /// any valid module address range. 162 //------------------------------------------------------------------ 163 static FileSpec 164 GetModuleFileSpecForHostAddress (const void *host_addr); 165 166 //------------------------------------------------------------------ 167 /// If you have an executable that is in a bundle and want to get 168 /// back to the bundle directory from the path itself, this 169 /// function will change a path to a file within a bundle to the 170 /// bundle directory itself. 171 /// 172 /// @param[in] file 173 /// A file spec that might point to a file in a bundle. 174 /// 175 /// @param[out] bundle_directory 176 /// An object will be filled in with the bundle directory for 177 /// the bundle when \b true is returned. Otherwise \a file is 178 /// left untouched and \b false is returned. 179 /// 180 /// @return 181 /// \b true if \a file was resolved in \a bundle_directory, 182 /// \b false otherwise. 183 //------------------------------------------------------------------ 184 static bool 185 GetBundleDirectory (const FileSpec &file, FileSpec &bundle_directory); 186 187 //------------------------------------------------------------------ 188 /// When executable files may live within a directory, where the 189 /// directory represents an executable bundle (like the MacOSX 190 /// app bundles), then locate the executable within the containing 191 /// bundle. 192 /// 193 /// @param[in,out] file 194 /// A file spec that currently points to the bundle that will 195 /// be filled in with the executable path within the bundle 196 /// if \b true is returned. Otherwise \a file is left untouched. 197 /// 198 /// @return 199 /// \b true if \a file was resolved, \b false if this function 200 /// was not able to resolve the path. 201 //------------------------------------------------------------------ 202 static bool 203 ResolveExecutableInBundle (FileSpec &file); 204 205 //------------------------------------------------------------------ 206 /// Set a string that can be displayed if host application crashes. 207 /// 208 /// Some operating systems have the ability to print a description 209 /// for shared libraries when a program crashes. If the host OS 210 /// supports such a mechanism, it should be implemented to help 211 /// with crash triage. 212 /// 213 /// @param[in] format 214 /// A printf format that will be used to form a new crash 215 /// description string. 216 //------------------------------------------------------------------ 217 static void 218 SetCrashDescriptionWithFormat (const char *format, ...) __attribute__ ((format (printf, 1, 2))); 219 220 static void 221 SetCrashDescription (const char *description); 222 223 static uint32_t 224 FindProcesses (const ProcessInstanceInfoMatch &match_info, 225 ProcessInstanceInfoList &proc_infos); 226 227 typedef std::map<lldb::pid_t, bool> TidMap; 228 typedef std::pair<lldb::pid_t, bool> TidPair; 229 static bool 230 FindProcessThreads (const lldb::pid_t pid, TidMap &tids_to_attach); 231 232 static bool 233 GetProcessInfo (lldb::pid_t pid, ProcessInstanceInfo &proc_info); 234 235 #if defined (__APPLE__) || defined (__linux__) || defined (__FreeBSD__) || defined (__GLIBC__) || defined (__NetBSD__) 236 #if !defined(__ANDROID__) && !defined(__ANDROID_NDK__) 237 238 static short GetPosixspawnFlags(const ProcessLaunchInfo &launch_info); 239 240 static Error LaunchProcessPosixSpawn(const char *exe_path, const ProcessLaunchInfo &launch_info, lldb::pid_t &pid); 241 242 static bool AddPosixSpawnFileAction(void *file_actions, const FileAction *info, Log *log, Error &error); 243 244 #endif // !defined(__ANDROID__) && !defined(__ANDROID_NDK__) 245 #endif // defined (__APPLE__) || defined (__linux__) || defined (__FreeBSD__) || defined (__GLIBC__) || defined(__NetBSD__) 246 247 static const lldb::UnixSignalsSP & 248 GetUnixSignals(); 249 250 static Error 251 LaunchProcess (ProcessLaunchInfo &launch_info); 252 253 //------------------------------------------------------------------ 254 /// Perform expansion of the command-line for this launch info 255 /// This can potentially involve wildcard expansion 256 // environment variable replacement, and whatever other 257 // argument magic the platform defines as part of its typical 258 // user experience 259 //------------------------------------------------------------------ 260 static Error 261 ShellExpandArguments (ProcessLaunchInfo &launch_info); 262 263 static Error 264 RunShellCommand(const char *command, // Shouldn't be NULL 265 const FileSpec &working_dir, // Pass empty FileSpec to use the current working directory 266 int *status_ptr, // Pass NULL if you don't want the process exit status 267 int *signo_ptr, // Pass NULL if you don't want the signal that caused the process to exit 268 std::string *command_output, // Pass NULL if you don't want the command output 269 uint32_t timeout_sec, 270 bool run_in_default_shell = true); 271 272 static Error 273 RunShellCommand(const Args& args, 274 const FileSpec &working_dir, // Pass empty FileSpec to use the current working directory 275 int *status_ptr, // Pass NULL if you don't want the process exit status 276 int *signo_ptr, // Pass NULL if you don't want the signal that caused the process to exit 277 std::string *command_output, // Pass NULL if you don't want the command output 278 uint32_t timeout_sec, 279 bool run_in_default_shell = true); 280 281 static lldb::DataBufferSP 282 GetAuxvData (lldb_private::Process *process); 283 284 static lldb::DataBufferSP 285 GetAuxvData (lldb::pid_t pid); 286 287 static bool 288 OpenFileInExternalEditor (const FileSpec &file_spec, 289 uint32_t line_no); 290 291 static size_t 292 GetEnvironment (StringList &env); 293 }; 294 295 } // namespace lldb_private 296 297 #endif // #if defined(__cplusplus) 298 #endif // liblldb_Host_h_ 299