Host.h revision 1831e78a6253392fca1c99e555e7adaa3f372647
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 "lldb/lldb-private.h" 17#include "lldb/Core/StringList.h" 18 19namespace lldb_private { 20 21//---------------------------------------------------------------------- 22/// @class Host Host.h "lldb/Host/Host.h" 23/// @brief A class that provides host computer information. 24/// 25/// Host is a class that answers information about the host operating 26/// system. 27//---------------------------------------------------------------------- 28class Host 29{ 30public: 31 typedef bool (*MonitorChildProcessCallback) (void *callback_baton, 32 lldb::pid_t pid, 33 bool exited, 34 int signal, // Zero for no signal 35 int status); // Exit value of process if signal is zero 36 37 //------------------------------------------------------------------ 38 /// Start monitoring a child process. 39 /// 40 /// Allows easy monitoring of child processes. \a callback will be 41 /// called when the child process exits or if it gets a signal. The 42 /// callback will only be called with signals if \a monitor_signals 43 /// is \b true. \a callback will usually be called from another 44 /// thread so the callback function must be thread safe. 45 /// 46 /// When the callback gets called, the return value indicates if 47 /// minotoring should stop. If \b true is returned from \a callback 48 /// the information will be removed. If \b false is returned then 49 /// monitoring will continue. If the child process exits, the 50 /// monitoring will automatically stop after the callback returned 51 /// ragardless of the callback return value. 52 /// 53 /// @param[in] callback 54 /// A function callback to call when a child receives a signal 55 /// (if \a monitor_signals is true) or a child exits. 56 /// 57 /// @param[in] callback_baton 58 /// A void * of user data that will be pass back when 59 /// \a callback is called. 60 /// 61 /// @param[in] pid 62 /// The process ID of a child process to monitor, -1 for all 63 /// processes. 64 /// 65 /// @param[in] monitor_signals 66 /// If \b true the callback will get called when the child 67 /// process gets a signal. If \b false, the callback will only 68 /// get called if the child process exits. 69 /// 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 lldb::DataBufferSP 418 GetAuxvData (lldb_private::Process *process); 419 420 static lldb::TargetSP 421 GetDummyTarget (Debugger &debugger); 422 423 static bool 424 OpenFileInExternalEditor (const FileSpec &file_spec, 425 uint32_t line_no); 426 427 static void 428 Backtrace (Stream &strm, uint32_t max_frames); 429 430 static size_t 431 GetEnvironment (StringList &env); 432 433 enum DynamicLibraryOpenOptions 434 { 435 eDynamicLibraryOpenOptionLazy = (1u << 0), // Lazily resolve symbols in this dynamic library 436 eDynamicLibraryOpenOptionLocal = (1u << 1), // Only open a shared library with local access (hide it from the global symbol namespace) 437 eDynamicLibraryOpenOptionLimitGetSymbol = (1u << 2) // DynamicLibraryGetSymbol calls on this handle will only return matches from this shared library 438 }; 439 static void * 440 DynamicLibraryOpen (const FileSpec &file_spec, 441 uint32_t options, 442 Error &error); 443 444 static Error 445 DynamicLibraryClose (void *dynamic_library_handle); 446 447 static void * 448 DynamicLibraryGetSymbol (void *dynamic_library_handle, 449 const char *symbol_name, 450 Error &error); 451}; 452 453} // namespace lldb_private 454 455#endif // #if defined(__cplusplus) 456#endif // liblldb_Host_h_ 457