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