Host.h revision 7e5fa7fc1f8efd24c078e063b2c4b5e13ba5be20
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 static bool 100 GetOSVersion (uint32_t &major, 101 uint32_t &minor, 102 uint32_t &update); 103 104 static bool 105 GetOSBuildString (std::string &s); 106 107 static bool 108 GetOSKernelDescription (std::string &s); 109 110 static bool 111 GetHostname (std::string &s); 112 113 static const char * 114 GetUserName (uint32_t uid, std::string &user_name); 115 116 static const char * 117 GetGroupName (uint32_t gid, std::string &group_name); 118 119 //------------------------------------------------------------------ 120 /// Gets the host architecture. 121 /// 122 /// @return 123 /// A const architecture object that represents the host 124 /// architecture. 125 //------------------------------------------------------------------ 126 enum SystemDefaultArchitecture 127 { 128 eSystemDefaultArchitecture, // The overall default architecture that applications will run on this host 129 eSystemDefaultArchitecture32, // If this host supports 32 bit programs, return the default 32 bit arch 130 eSystemDefaultArchitecture64 // If this host supports 64 bit programs, return the default 64 bit arch 131 }; 132 133 static const ArchSpec & 134 GetArchitecture (SystemDefaultArchitecture arch_kind = eSystemDefaultArchitecture); 135 136 //------------------------------------------------------------------ 137 /// Gets the host vendor string. 138 /// 139 /// @return 140 /// A const string object containing the host vendor name. 141 //------------------------------------------------------------------ 142 static const ConstString & 143 GetVendorString (); 144 145 //------------------------------------------------------------------ 146 /// Gets the host Operating System (OS) string. 147 /// 148 /// @return 149 /// A const string object containing the host OS name. 150 //------------------------------------------------------------------ 151 static const ConstString & 152 GetOSString (); 153 154 //------------------------------------------------------------------ 155 /// Gets the host target triple as a const string. 156 /// 157 /// @return 158 /// A const string object containing the host target triple. 159 //------------------------------------------------------------------ 160 static const ConstString & 161 GetTargetTriple (); 162 163 //------------------------------------------------------------------ 164 /// Get the process ID for the calling process. 165 /// 166 /// @return 167 /// The process ID for the current process. 168 //------------------------------------------------------------------ 169 static lldb::pid_t 170 GetCurrentProcessID (); 171 172 //------------------------------------------------------------------ 173 /// Get the thread ID for the calling thread in the current process. 174 /// 175 /// @return 176 /// The thread ID for the calling thread in the current process. 177 //------------------------------------------------------------------ 178 static lldb::tid_t 179 GetCurrentThreadID (); 180 181 static const char * 182 GetSignalAsCString (int signo); 183 184 static void 185 WillTerminate (); 186 //------------------------------------------------------------------ 187 /// Host specific thread created function call. 188 /// 189 /// This function call lets the current host OS do any thread 190 /// specific initialization that it needs, including naming the 191 /// thread. No cleanup routine is exptected to be called 192 /// 193 /// @param[in] name 194 /// The current thread's name in the current process. 195 //------------------------------------------------------------------ 196 static void 197 ThreadCreated (const char *name); 198 199 static lldb::thread_t 200 ThreadCreate (const char *name, 201 lldb::thread_func_t function, 202 lldb::thread_arg_t thread_arg, 203 Error *err); 204 205 static bool 206 ThreadCancel (lldb::thread_t thread, 207 Error *error); 208 209 static bool 210 ThreadDetach (lldb::thread_t thread, 211 Error *error); 212 static bool 213 ThreadJoin (lldb::thread_t thread, 214 lldb::thread_result_t *thread_result_ptr, 215 Error *error); 216 217 //------------------------------------------------------------------ 218 /// Gets the name of a thread in a process. 219 /// 220 /// This function will name a thread in a process using it's own 221 /// thread name pool, and also will attempt to set a thread name 222 /// using any supported host OS APIs. 223 /// 224 /// @param[in] pid 225 /// The process ID in which we are trying to get the name of 226 /// a thread. 227 /// 228 /// @param[in] tid 229 /// The thread ID for which we are trying retrieve the name of. 230 /// 231 /// @return 232 /// A NULL terminate C string name that is owned by a static 233 /// global string pool, or NULL if there is no matching thread 234 /// name. This string does not need to be freed. 235 //------------------------------------------------------------------ 236 static const char * 237 GetThreadName (lldb::pid_t pid, lldb::tid_t tid); 238 239 //------------------------------------------------------------------ 240 /// Sets the name of a thread in the current process. 241 /// 242 /// @param[in] pid 243 /// The process ID in which we are trying to name a thread. 244 /// 245 /// @param[in] tid 246 /// The thread ID which we are trying to name. 247 /// 248 /// @param[in] name 249 /// The current thread's name in the current process to \a name. 250 /// 251 /// @return 252 /// \b true if the thread name was able to be set, \b false 253 /// otherwise. 254 //------------------------------------------------------------------ 255 static void 256 SetThreadName (lldb::pid_t pid, lldb::tid_t tid, const char *name); 257 258 //------------------------------------------------------------------ 259 /// Gets the FileSpec of the current process (the process that 260 /// that is running the LLDB code). 261 /// 262 /// @return 263 /// \b A file spec with the program name. 264 //------------------------------------------------------------------ 265 static FileSpec 266 GetProgramFileSpec (); 267 268 //------------------------------------------------------------------ 269 /// Given an address in the current process (the process that 270 /// is running the LLDB code), return the name of the module that 271 /// it comes from. This can be useful when you need to know the 272 /// path to the shared library that your code is running in for 273 /// loading resources that are relative to your binary. 274 /// 275 /// @param[in] host_addr 276 /// The pointer to some code in the current process. 277 /// 278 /// @return 279 /// \b A file spec with the module that contains \a host_addr, 280 /// which may be invalid if \a host_addr doesn't fall into 281 /// any valid module address range. 282 //------------------------------------------------------------------ 283 static FileSpec 284 GetModuleFileSpecForHostAddress (const void *host_addr); 285 286 287 //------------------------------------------------------------------ 288 /// When executable files may live within a directory, where the 289 /// directory represents an executable bundle (like the MacOSX 290 /// app bundles), the locate the executable within the containing 291 /// bundle. 292 /// 293 /// @param[in,out] file 294 /// A file spec that currently points to the bundle that will 295 /// be filled in with the executable path within the bundle 296 /// if \b true is returned. Otherwise \a file is left untouched. 297 /// 298 /// @return 299 /// \b true if \a file was resolved, \b false if this function 300 /// was not able to resolve the path. 301 //------------------------------------------------------------------ 302 static bool 303 ResolveExecutableInBundle (FileSpec &file); 304 305 //------------------------------------------------------------------ 306 /// Find a resource files that are related to LLDB. 307 /// 308 /// Operating systems have different ways of storing shared 309 /// libraries and related resources. This function abstracts the 310 /// access to these paths. 311 /// 312 /// @param[in] path_type 313 /// The type of LLDB resource path you are looking for. If the 314 /// enumeration ends with "Dir", then only the \a file_spec's 315 /// directory member gets filled in. 316 /// 317 /// @param[in] file_spec 318 /// A file spec that gets filled in with the appriopriate path. 319 /// 320 /// @return 321 /// \b true if \a resource_path was resolved, \a false otherwise. 322 //------------------------------------------------------------------ 323 static bool 324 GetLLDBPath (PathType path_type, 325 FileSpec &file_spec); 326 327 //------------------------------------------------------------------ 328 /// Set a string that can be displayed if host application crashes. 329 /// 330 /// Some operating systems have the ability to print a description 331 /// for shared libraries when a program crashes. If the host OS 332 /// supports such a mechanism, it should be implemented to help 333 /// with crash triage. 334 /// 335 /// @param[in] format 336 /// A printf format that will be used to form a new crash 337 /// description string. 338 //------------------------------------------------------------------ 339 static void 340 SetCrashDescriptionWithFormat (const char *format, ...) __attribute__ ((format (printf, 1, 2))); 341 342 static void 343 SetCrashDescription (const char *description); 344 345 static uint32_t 346 FindProcesses (const ProcessInstanceInfoMatch &match_info, 347 ProcessInstanceInfoList &proc_infos); 348 349 static bool 350 GetProcessInfo (lldb::pid_t pid, ProcessInstanceInfo &proc_info); 351 352 static lldb::pid_t 353 LaunchApplication (const FileSpec &app_file_spec); 354 355 static Error 356 LaunchProcess (ProcessLaunchInfo &launch_info); 357 358 static bool 359 OpenFileInExternalEditor (const FileSpec &file_spec, 360 uint32_t line_no); 361 362 static void 363 Backtrace (Stream &strm, uint32_t max_frames); 364 365 static size_t 366 GetEnvironment (StringList &env); 367 368 enum DynamicLibraryOpenOptions 369 { 370 eDynamicLibraryOpenOptionLazy = (1u << 0), // Lazily resolve symbols in this dynamic library 371 eDynamicLibraryOpenOptionLocal = (1u << 1), // Only open a shared library with local access (hide it from the global symbol namespace) 372 eDynamicLibraryOpenOptionLimitGetSymbol = (1u << 2) // DynamicLibraryGetSymbol calls on this handle will only return matches from this shared library 373 }; 374 static void * 375 DynamicLibraryOpen (const FileSpec &file_spec, 376 uint32_t options, 377 Error &error); 378 379 static Error 380 DynamicLibraryClose (void *dynamic_library_handle); 381 382 static void * 383 DynamicLibraryGetSymbol (void *dynamic_library_handle, 384 const char *symbol_name, 385 Error &error); 386}; 387 388} // namespace lldb_private 389 390#endif // #if defined(__cplusplus) 391#endif // liblldb_Host_h_ 392