Host.h revision bb0c91fa5e8516016908dbd4cb79542ea4312b41
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 15#include "lldb/lldb-private.h" 16#include "lldb/Core/StringList.h" 17 18namespace lldb_private { 19 20//---------------------------------------------------------------------- 21/// @class Host Host.h "lldb/Host/Host.h" 22/// @brief A class that provides host computer information. 23/// 24/// Host is a class that answers information about the host operating 25/// system. 26//---------------------------------------------------------------------- 27class Host 28{ 29public: 30 typedef bool (*MonitorChildProcessCallback) (void *callback_baton, 31 lldb::pid_t pid, 32 int signal, // Zero for no signal 33 int status); // Exit value of process if signal is zero 34 35 //------------------------------------------------------------------ 36 /// Start monitoring a child process. 37 /// 38 /// Allows easy monitoring of child processes. \a callback will be 39 /// called when the child process exits or if it gets a signal. The 40 /// callback will only be called with signals if \a monitor_signals 41 /// is \b true. \a callback will usually be called from another 42 /// thread so the callback function must be thread safe. 43 /// 44 /// When the callback gets called, the return value indicates if 45 /// minotoring should stop. If \b true is returned from \a callback 46 /// the information will be removed. If \b false is returned then 47 /// monitoring will continue. If the child process exits, the 48 /// monitoring will automatically stop after the callback returned 49 /// ragardless of the callback return value. 50 /// 51 /// @param[in] callback 52 /// A function callback to call when a child receives a signal 53 /// (if \a monitor_signals is true) or a child exits. 54 /// 55 /// @param[in] callback_baton 56 /// A void * of user data that will be pass back when 57 /// \a callback is called. 58 /// 59 /// @param[in] pid 60 /// The process ID of a child process to monitor, -1 for all 61 /// processes. 62 /// 63 /// @param[in] monitor_signals 64 /// If \b true the callback will get called when the child 65 /// process gets a signal. If \b false, the callback will only 66 /// get called if the child process exits. 67 /// 68 /// @return 69 /// A thread handle that can be used to cancel the thread that 70 /// was spawned to monitor \a pid. 71 /// 72 /// @see static void Host::StopMonitoringChildProcess (uint32_t) 73 //------------------------------------------------------------------ 74 static lldb::thread_t 75 StartMonitoringChildProcess (MonitorChildProcessCallback callback, 76 void *callback_baton, 77 lldb::pid_t pid, 78 bool monitor_signals); 79 80 //------------------------------------------------------------------ 81 /// Get the host page size. 82 /// 83 /// @return 84 /// The size in bytes of a VM page on the host system. 85 //------------------------------------------------------------------ 86 static size_t 87 GetPageSize(); 88 89 //------------------------------------------------------------------ 90 /// Returns the endianness of the host system. 91 /// 92 /// @return 93 /// Returns the endianness of the host system as a lldb::ByteOrder 94 /// enumeration. 95 //------------------------------------------------------------------ 96 static lldb::ByteOrder 97 GetByteOrder (); 98 99 //------------------------------------------------------------------ 100 /// Gets the host kernel architecture. 101 /// 102 /// @return 103 /// A const architecture object that represents the host kernel 104 /// architecture. 105 //------------------------------------------------------------------ 106 static const ArchSpec & 107 GetArchitecture (); 108 109 //------------------------------------------------------------------ 110 /// Gets the host vendor string. 111 /// 112 /// @return 113 /// A const string object containing the host vendor name. 114 //------------------------------------------------------------------ 115 static const ConstString & 116 GetVendorString (); 117 118 //------------------------------------------------------------------ 119 /// Gets the host Operating System (OS) string. 120 /// 121 /// @return 122 /// A const string object containing the host OS name. 123 //------------------------------------------------------------------ 124 static const ConstString & 125 GetOSString (); 126 127 //------------------------------------------------------------------ 128 /// Gets the host target triple as a const string. 129 /// 130 /// @return 131 /// A const string object containing the host target triple. 132 //------------------------------------------------------------------ 133 static const ConstString & 134 GetTargetTriple (); 135 136 //------------------------------------------------------------------ 137 /// Get the process ID for the calling process. 138 /// 139 /// @return 140 /// The process ID for the current process. 141 //------------------------------------------------------------------ 142 static lldb::pid_t 143 GetCurrentProcessID (); 144 145 //------------------------------------------------------------------ 146 /// Get the thread ID for the calling thread in the current process. 147 /// 148 /// @return 149 /// The thread ID for the calling thread in the current process. 150 //------------------------------------------------------------------ 151 static lldb::tid_t 152 GetCurrentThreadID (); 153 154 static const char * 155 GetSignalAsCString (int signo); 156 157 static void 158 WillTerminate (); 159 //------------------------------------------------------------------ 160 /// Host specific thread created function call. 161 /// 162 /// This function call lets the current host OS do any thread 163 /// specific initialization that it needs, including naming the 164 /// thread. No cleanup routine is exptected to be called 165 /// 166 /// @param[in] name 167 /// The current thread's name in the current process. 168 //------------------------------------------------------------------ 169 static void 170 ThreadCreated (const char *name); 171 172 static lldb::thread_t 173 ThreadCreate (const char *name, 174 lldb::thread_func_t function, 175 lldb::thread_arg_t thread_arg, 176 Error *err); 177 178 static bool 179 ThreadCancel (lldb::thread_t thread, 180 Error *error); 181 182 static bool 183 ThreadDetach (lldb::thread_t thread, 184 Error *error); 185 static bool 186 ThreadJoin (lldb::thread_t thread, 187 lldb::thread_result_t *thread_result_ptr, 188 Error *error); 189 190 //------------------------------------------------------------------ 191 /// Gets the name of a thread in a process. 192 /// 193 /// This function will name a thread in a process using it's own 194 /// thread name pool, and also will attempt to set a thread name 195 /// using any supported host OS APIs. 196 /// 197 /// @param[in] pid 198 /// The process ID in which we are trying to get the name of 199 /// a thread. 200 /// 201 /// @param[in] tid 202 /// The thread ID for which we are trying retrieve the name of. 203 /// 204 /// @return 205 /// A NULL terminate C string name that is owned by a static 206 /// global string pool, or NULL if there is no matching thread 207 /// name. This string does not need to be freed. 208 //------------------------------------------------------------------ 209 static const char * 210 GetThreadName (lldb::pid_t pid, lldb::tid_t tid); 211 212 //------------------------------------------------------------------ 213 /// Sets the name of a thread in the current process. 214 /// 215 /// @param[in] pid 216 /// The process ID in which we are trying to name a thread. 217 /// 218 /// @param[in] tid 219 /// The thread ID which we are trying to name. 220 /// 221 /// @param[in] name 222 /// The current thread's name in the current process to \a name. 223 /// 224 /// @return 225 /// \b true if the thread name was able to be set, \b false 226 /// otherwise. 227 //------------------------------------------------------------------ 228 static void 229 SetThreadName (lldb::pid_t pid, lldb::tid_t tid, const char *name); 230 231 //------------------------------------------------------------------ 232 /// Gets the FileSpec of the current process (the process that 233 /// that is running the LLDB code). 234 /// 235 /// @return 236 /// \b A file spec with the program name. 237 //------------------------------------------------------------------ 238 static FileSpec 239 GetProgramFileSpec (); 240 241 //------------------------------------------------------------------ 242 /// Given an address in the current process (the process that 243 /// is running the LLDB code), return the name of the module that 244 /// it comes from. This can be useful when you need to know the 245 /// path to the shared library that your code is running in for 246 /// loading resources that are relative to your binary. 247 /// 248 /// @param[in] host_addr 249 /// The pointer to some code in the current process. 250 /// 251 /// @return 252 /// \b A file spec with the module that contains \a host_addr, 253 /// which may be invalid if \a host_addr doesn't fall into 254 /// any valid module address range. 255 //------------------------------------------------------------------ 256 static FileSpec 257 GetModuleFileSpecForHostAddress (const void *host_addr); 258 259 260 //------------------------------------------------------------------ 261 /// When executable files may live within a directory, where the 262 /// directory represents an executable bundle (like the MacOSX 263 /// app bundles), the locate the executable within the containing 264 /// bundle. 265 /// 266 /// @param[in,out] file 267 /// A file spec that currently points to the bundle that will 268 /// be filled in with the executable path within the bundle 269 /// if \b true is returned. Otherwise \a file is left untouched. 270 /// 271 /// @return 272 /// \b true if \a file was resolved, \b false if this function 273 /// was not able to resolve the path. 274 //------------------------------------------------------------------ 275 static bool 276 ResolveExecutableInBundle (FileSpec &file); 277 278 //------------------------------------------------------------------ 279 /// Find a resource files that are related to LLDB. 280 /// 281 /// Operating systems have different ways of storing shared 282 /// libraries and related resources. This function abstracts the 283 /// access to these paths. 284 /// 285 /// @param[in] path_type 286 /// The type of LLDB resource path you are looking for. If the 287 /// enumeration ends with "Dir", then only the \a file_spec's 288 /// directory member gets filled in. 289 /// 290 /// @param[in] file_spec 291 /// A file spec that gets filled in with the appriopriate path. 292 /// 293 /// @return 294 /// \b true if \a resource_path was resolved, \a false otherwise. 295 //------------------------------------------------------------------ 296 static bool 297 GetLLDBPath (lldb::PathType path_type, 298 FileSpec &file_spec); 299 300 static uint32_t 301 ListProcessesMatchingName (const char *name, StringList &matches, std::vector<lldb::pid_t> &pids); 302 303 static ArchSpec 304 GetArchSpecForExistingProcess (lldb::pid_t pid); 305 306 static ArchSpec 307 GetArchSpecForExistingProcess (const char *process_name); 308 309 static lldb::pid_t 310 LaunchApplication (const FileSpec &app_file_spec); 311 312 static lldb::pid_t 313 LaunchInNewTerminal (const char *tty_name, // Optional partial or full tty name ("/dev/ttys000" or "ttys000") 314 const char **argv, // argv[0] is executable 315 const char **envp, 316 const ArchSpec *arch_spec, 317 bool stop_at_entry, 318 bool disable_aslr); 319 320 static bool 321 OpenFileInExternalEditor (const FileSpec &file_spec, uint32_t line_no); 322 323}; 324 325} // namespace lldb_private 326 327#endif // #if defined(__cplusplus) 328#endif // liblldb_Host_h_ 329