Host.h revision b924eb6c5250a9909dc55ac736d231f7ccae423b
15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//===-- Host.h --------------------------------------------------*- C++ -*-===// 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The LLVM Compiler Infrastructure 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// This file is distributed under the University of Illinois Open Source 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// License. See LICENSE.TXT for details. 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 85d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles)//===----------------------------------------------------------------------===// 95d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef liblldb_Host_h_ 115d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles)#define liblldb_Host_h_ 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined(__cplusplus) 135d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) 142a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)#include <stdarg.h> 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "lldb/lldb-private.h" 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "lldb/Core/StringList.h" 182a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace lldb_private { 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//---------------------------------------------------------------------- 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// @class Host Host.h "lldb/Host/Host.h" 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// @brief A class that provides host computer information. 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// Host is a class that answers information about the host operating 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// system. 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//---------------------------------------------------------------------- 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class Host 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles){ 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)public: 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) typedef bool (*MonitorChildProcessCallback) (void *callback_baton, 322a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) lldb::pid_t pid, 335d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) bool exited, 34c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) int signal, // Zero for no signal 35c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) int status); // Exit value of process if signal is zero 36c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 37c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) //------------------------------------------------------------------ 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Start monitoring a child process. 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 402a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) /// Allows easy monitoring of child processes. \a callback will be 415d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// called when the child process exits or if it gets a signal. The 425d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// callback will only be called with signals if \a monitor_signals 435d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// is \b true. \a callback will usually be called from another 445d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// thread so the callback function must be thread safe. 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// When the callback gets called, the return value indicates if 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// minotoring should stop. If \b true is returned from \a callback 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// the information will be removed. If \b false is returned then 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// monitoring will continue. If the child process exits, the 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// monitoring will automatically stop after the callback returned 515d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// ragardless of the callback return value. 525d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] callback 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// A function callback to call when a child receives a signal 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// (if \a monitor_signals is true) or a child exits. 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 575d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// @param[in] callback_baton 585d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// A void * of user data that will be pass back when 595d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// \a callback is called. 602a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) /// 615d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// @param[in] pid 625d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// The process ID of a child process to monitor, -1 for all 635d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// processes. 645d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] monitor_signals 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// If \b true the callback will get called when the child 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// process gets a signal. If \b false, the callback will only 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// get called if the child process exits. 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 70 /// @return 71 /// A thread handle that can be used to cancel the thread that 72 /// was spawned to monitor \a pid. 73 /// 74 /// @see static void Host::StopMonitoringChildProcess (uint32_t) 75 //------------------------------------------------------------------ 76 static lldb::thread_t 77 StartMonitoringChildProcess (MonitorChildProcessCallback callback, 78 void *callback_baton, 79 lldb::pid_t pid, 80 bool monitor_signals); 81 82 //------------------------------------------------------------------ 83 /// Get the host page size. 84 /// 85 /// @return 86 /// The size in bytes of a VM page on the host system. 87 //------------------------------------------------------------------ 88 static size_t 89 GetPageSize(); 90 91 //------------------------------------------------------------------ 92 /// Returns the endianness of the host system. 93 /// 94 /// @return 95 /// Returns the endianness of the host system as a lldb::ByteOrder 96 /// enumeration. 97 //------------------------------------------------------------------ 98 static lldb::ByteOrder 99 GetByteOrder (); 100 101 static bool 102 GetOSVersion (uint32_t &major, 103 uint32_t &minor, 104 uint32_t &update); 105 106 static bool 107 GetOSBuildString (std::string &s); 108 109 static bool 110 GetOSKernelDescription (std::string &s); 111 112 static bool 113 GetHostname (std::string &s); 114 115 static const char * 116 GetUserName (uint32_t uid, std::string &user_name); 117 118 static const char * 119 GetGroupName (uint32_t gid, std::string &group_name); 120 121 static uint32_t 122 GetUserID (); 123 124 static uint32_t 125 GetGroupID (); 126 127 static uint32_t 128 GetEffectiveUserID (); 129 130 static uint32_t 131 GetEffectiveGroupID (); 132 133 134 enum SystemLogType 135 { 136 eSystemLogWarning, 137 eSystemLogError 138 }; 139 140 static void 141 SystemLog (SystemLogType type, const char *format, ...) __attribute__ ((format (printf, 2, 3))); 142 143 static void 144 SystemLog (SystemLogType type, const char *format, va_list args); 145 146 //------------------------------------------------------------------ 147 /// Gets the host architecture. 148 /// 149 /// @return 150 /// A const architecture object that represents the host 151 /// architecture. 152 //------------------------------------------------------------------ 153 enum SystemDefaultArchitecture 154 { 155 eSystemDefaultArchitecture, // The overall default architecture that applications will run on this host 156 eSystemDefaultArchitecture32, // If this host supports 32 bit programs, return the default 32 bit arch 157 eSystemDefaultArchitecture64 // If this host supports 64 bit programs, return the default 64 bit arch 158 }; 159 160 static const ArchSpec & 161 GetArchitecture (SystemDefaultArchitecture arch_kind = eSystemDefaultArchitecture); 162 163 //------------------------------------------------------------------ 164 /// Gets the host vendor string. 165 /// 166 /// @return 167 /// A const string object containing the host vendor name. 168 //------------------------------------------------------------------ 169 static const ConstString & 170 GetVendorString (); 171 172 //------------------------------------------------------------------ 173 /// Gets the host Operating System (OS) string. 174 /// 175 /// @return 176 /// A const string object containing the host OS name. 177 //------------------------------------------------------------------ 178 static const ConstString & 179 GetOSString (); 180 181 //------------------------------------------------------------------ 182 /// Gets the host target triple as a const string. 183 /// 184 /// @return 185 /// A const string object containing the host target triple. 186 //------------------------------------------------------------------ 187 static const ConstString & 188 GetTargetTriple (); 189 190 //------------------------------------------------------------------ 191 /// Get the process ID for the calling process. 192 /// 193 /// @return 194 /// The process ID for the current process. 195 //------------------------------------------------------------------ 196 static lldb::pid_t 197 GetCurrentProcessID (); 198 199 //------------------------------------------------------------------ 200 /// Get the thread ID for the calling thread in the current process. 201 /// 202 /// @return 203 /// The thread ID for the calling thread in the current process. 204 //------------------------------------------------------------------ 205 static lldb::tid_t 206 GetCurrentThreadID (); 207 208 //------------------------------------------------------------------ 209 /// Get the thread token (the one returned by ThreadCreate when the thread was created) for the 210 /// calling thread in the current process. 211 /// 212 /// @return 213 /// The thread token for the calling thread in the current process. 214 //------------------------------------------------------------------ 215 static lldb::thread_t 216 GetCurrentThread (); 217 218 static const char * 219 GetSignalAsCString (int signo); 220 221 static void 222 WillTerminate (); 223 //------------------------------------------------------------------ 224 /// Host specific thread created function call. 225 /// 226 /// This function call lets the current host OS do any thread 227 /// specific initialization that it needs, including naming the 228 /// thread. No cleanup routine is exptected to be called 229 /// 230 /// @param[in] name 231 /// The current thread's name in the current process. 232 //------------------------------------------------------------------ 233 static void 234 ThreadCreated (const char *name); 235 236 static lldb::thread_t 237 ThreadCreate (const char *name, 238 lldb::thread_func_t function, 239 lldb::thread_arg_t thread_arg, 240 Error *err); 241 242 static bool 243 ThreadCancel (lldb::thread_t thread, 244 Error *error); 245 246 static bool 247 ThreadDetach (lldb::thread_t thread, 248 Error *error); 249 static bool 250 ThreadJoin (lldb::thread_t thread, 251 lldb::thread_result_t *thread_result_ptr, 252 Error *error); 253 254 //------------------------------------------------------------------ 255 /// Gets the name of a thread in a process. 256 /// 257 /// This function will name a thread in a process using it's own 258 /// thread name pool, and also will attempt to set a thread name 259 /// using any supported host OS APIs. 260 /// 261 /// @param[in] pid 262 /// The process ID in which we are trying to get the name of 263 /// a thread. 264 /// 265 /// @param[in] tid 266 /// The thread ID for which we are trying retrieve the name of. 267 /// 268 /// @return 269 /// A NULL terminate C string name that is owned by a static 270 /// global string pool, or NULL if there is no matching thread 271 /// name. This string does not need to be freed. 272 //------------------------------------------------------------------ 273 static const char * 274 GetThreadName (lldb::pid_t pid, lldb::tid_t tid); 275 276 //------------------------------------------------------------------ 277 /// Sets the name of a thread in the current process. 278 /// 279 /// @param[in] pid 280 /// The process ID in which we are trying to name a thread. 281 /// 282 /// @param[in] tid 283 /// The thread ID which we are trying to name. 284 /// 285 /// @param[in] name 286 /// The current thread's name in the current process to \a name. 287 /// 288 /// @return 289 /// \b true if the thread name was able to be set, \b false 290 /// otherwise. 291 //------------------------------------------------------------------ 292 static void 293 SetThreadName (lldb::pid_t pid, lldb::tid_t tid, const char *name); 294 295 //------------------------------------------------------------------ 296 /// Gets the FileSpec of the current process (the process that 297 /// that is running the LLDB code). 298 /// 299 /// @return 300 /// \b A file spec with the program name. 301 //------------------------------------------------------------------ 302 static FileSpec 303 GetProgramFileSpec (); 304 305 //------------------------------------------------------------------ 306 /// Given an address in the current process (the process that 307 /// is running the LLDB code), return the name of the module that 308 /// it comes from. This can be useful when you need to know the 309 /// path to the shared library that your code is running in for 310 /// loading resources that are relative to your binary. 311 /// 312 /// @param[in] host_addr 313 /// The pointer to some code in the current process. 314 /// 315 /// @return 316 /// \b A file spec with the module that contains \a host_addr, 317 /// which may be invalid if \a host_addr doesn't fall into 318 /// any valid module address range. 319 //------------------------------------------------------------------ 320 static FileSpec 321 GetModuleFileSpecForHostAddress (const void *host_addr); 322 323 324 325 //------------------------------------------------------------------ 326 /// If you have an executable that is in a bundle and want to get 327 /// back to the bundle directory from the path itself, this 328 /// function will change a path to a file within a bundle to the 329 /// bundle directory itself. 330 /// 331 /// @param[in] file 332 /// A file spec that might point to a file in a bundle. 333 /// 334 /// @param[out] bundle_directory 335 /// An object will be filled in with the bundle directory for 336 /// the bundle when \b true is returned. Otherwise \a file is 337 /// left untouched and \b false is returned. 338 /// 339 /// @return 340 /// \b true if \a file was resolved in \a bundle_directory, 341 /// \b false otherwise. 342 //------------------------------------------------------------------ 343 static bool 344 GetBundleDirectory (const FileSpec &file, FileSpec &bundle_directory); 345 346 //------------------------------------------------------------------ 347 /// When executable files may live within a directory, where the 348 /// directory represents an executable bundle (like the MacOSX 349 /// app bundles), the locate the executable within the containing 350 /// bundle. 351 /// 352 /// @param[in,out] file 353 /// A file spec that currently points to the bundle that will 354 /// be filled in with the executable path within the bundle 355 /// if \b true is returned. Otherwise \a file is left untouched. 356 /// 357 /// @return 358 /// \b true if \a file was resolved, \b false if this function 359 /// was not able to resolve the path. 360 //------------------------------------------------------------------ 361 static bool 362 ResolveExecutableInBundle (FileSpec &file); 363 364 //------------------------------------------------------------------ 365 /// Find a resource files that are related to LLDB. 366 /// 367 /// Operating systems have different ways of storing shared 368 /// libraries and related resources. This function abstracts the 369 /// access to these paths. 370 /// 371 /// @param[in] path_type 372 /// The type of LLDB resource path you are looking for. If the 373 /// enumeration ends with "Dir", then only the \a file_spec's 374 /// directory member gets filled in. 375 /// 376 /// @param[in] file_spec 377 /// A file spec that gets filled in with the appriopriate path. 378 /// 379 /// @return 380 /// \b true if \a resource_path was resolved, \a false otherwise. 381 //------------------------------------------------------------------ 382 static bool 383 GetLLDBPath (PathType path_type, 384 FileSpec &file_spec); 385 386 //------------------------------------------------------------------ 387 /// Set a string that can be displayed if host application crashes. 388 /// 389 /// Some operating systems have the ability to print a description 390 /// for shared libraries when a program crashes. If the host OS 391 /// supports such a mechanism, it should be implemented to help 392 /// with crash triage. 393 /// 394 /// @param[in] format 395 /// A printf format that will be used to form a new crash 396 /// description string. 397 //------------------------------------------------------------------ 398 static void 399 SetCrashDescriptionWithFormat (const char *format, ...) __attribute__ ((format (printf, 1, 2))); 400 401 static void 402 SetCrashDescription (const char *description); 403 404 static uint32_t 405 FindProcesses (const ProcessInstanceInfoMatch &match_info, 406 ProcessInstanceInfoList &proc_infos); 407 408 static bool 409 GetProcessInfo (lldb::pid_t pid, ProcessInstanceInfo &proc_info); 410 411 static lldb::pid_t 412 LaunchApplication (const FileSpec &app_file_spec); 413 414 static Error 415 LaunchProcess (ProcessLaunchInfo &launch_info); 416 417 static Error 418 RunShellCommand (const char *command, // Shouldn't be NULL 419 const char *working_dir, // Pass NULL to use the current working directory 420 int *status_ptr, // Pass NULL if you don't want the process exit status 421 int *signo_ptr, // Pass NULL if you don't want the signal that caused the process to exit 422 std::string *command_output, // Pass NULL if you don't want the command output 423 uint32_t timeout_sec, 424 const char *shell = "/bin/bash"); 425 426 static lldb::DataBufferSP 427 GetAuxvData (lldb_private::Process *process); 428 429 static lldb::TargetSP 430 GetDummyTarget (Debugger &debugger); 431 432 static bool 433 OpenFileInExternalEditor (const FileSpec &file_spec, 434 uint32_t line_no); 435 436 static void 437 Backtrace (Stream &strm, uint32_t max_frames); 438 439 static size_t 440 GetEnvironment (StringList &env); 441 442 enum DynamicLibraryOpenOptions 443 { 444 eDynamicLibraryOpenOptionLazy = (1u << 0), // Lazily resolve symbols in this dynamic library 445 eDynamicLibraryOpenOptionLocal = (1u << 1), // Only open a shared library with local access (hide it from the global symbol namespace) 446 eDynamicLibraryOpenOptionLimitGetSymbol = (1u << 2) // DynamicLibraryGetSymbol calls on this handle will only return matches from this shared library 447 }; 448 static void * 449 DynamicLibraryOpen (const FileSpec &file_spec, 450 uint32_t options, 451 Error &error); 452 453 static Error 454 DynamicLibraryClose (void *dynamic_library_handle); 455 456 static void * 457 DynamicLibraryGetSymbol (void *dynamic_library_handle, 458 const char *symbol_name, 459 Error &error); 460}; 461 462} // namespace lldb_private 463 464#endif // #if defined(__cplusplus) 465#endif // liblldb_Host_h_ 466