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