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