Host.h revision d1040dd360c07305a30d33b5d4501cb9dfb03114
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 static const char * 209 GetSignalAsCString (int signo); 210 211 static void 212 WillTerminate (); 213 //------------------------------------------------------------------ 214 /// Host specific thread created function call. 215 /// 216 /// This function call lets the current host OS do any thread 217 /// specific initialization that it needs, including naming the 218 /// thread. No cleanup routine is exptected to be called 219 /// 220 /// @param[in] name 221 /// The current thread's name in the current process. 222 //------------------------------------------------------------------ 223 static void 224 ThreadCreated (const char *name); 225 226 static lldb::thread_t 227 ThreadCreate (const char *name, 228 lldb::thread_func_t function, 229 lldb::thread_arg_t thread_arg, 230 Error *err); 231 232 static bool 233 ThreadCancel (lldb::thread_t thread, 234 Error *error); 235 236 static bool 237 ThreadDetach (lldb::thread_t thread, 238 Error *error); 239 static bool 240 ThreadJoin (lldb::thread_t thread, 241 lldb::thread_result_t *thread_result_ptr, 242 Error *error); 243 244 //------------------------------------------------------------------ 245 /// Gets the name of a thread in a process. 246 /// 247 /// This function will name a thread in a process using it's own 248 /// thread name pool, and also will attempt to set a thread name 249 /// using any supported host OS APIs. 250 /// 251 /// @param[in] pid 252 /// The process ID in which we are trying to get the name of 253 /// a thread. 254 /// 255 /// @param[in] tid 256 /// The thread ID for which we are trying retrieve the name of. 257 /// 258 /// @return 259 /// A NULL terminate C string name that is owned by a static 260 /// global string pool, or NULL if there is no matching thread 261 /// name. This string does not need to be freed. 262 //------------------------------------------------------------------ 263 static const char * 264 GetThreadName (lldb::pid_t pid, lldb::tid_t tid); 265 266 //------------------------------------------------------------------ 267 /// Sets the name of a thread in the current process. 268 /// 269 /// @param[in] pid 270 /// The process ID in which we are trying to name a thread. 271 /// 272 /// @param[in] tid 273 /// The thread ID which we are trying to name. 274 /// 275 /// @param[in] name 276 /// The current thread's name in the current process to \a name. 277 /// 278 /// @return 279 /// \b true if the thread name was able to be set, \b false 280 /// otherwise. 281 //------------------------------------------------------------------ 282 static void 283 SetThreadName (lldb::pid_t pid, lldb::tid_t tid, const char *name); 284 285 //------------------------------------------------------------------ 286 /// Gets the FileSpec of the current process (the process that 287 /// that is running the LLDB code). 288 /// 289 /// @return 290 /// \b A file spec with the program name. 291 //------------------------------------------------------------------ 292 static FileSpec 293 GetProgramFileSpec (); 294 295 //------------------------------------------------------------------ 296 /// Given an address in the current process (the process that 297 /// is running the LLDB code), return the name of the module that 298 /// it comes from. This can be useful when you need to know the 299 /// path to the shared library that your code is running in for 300 /// loading resources that are relative to your binary. 301 /// 302 /// @param[in] host_addr 303 /// The pointer to some code in the current process. 304 /// 305 /// @return 306 /// \b A file spec with the module that contains \a host_addr, 307 /// which may be invalid if \a host_addr doesn't fall into 308 /// any valid module address range. 309 //------------------------------------------------------------------ 310 static FileSpec 311 GetModuleFileSpecForHostAddress (const void *host_addr); 312 313 314 315 //------------------------------------------------------------------ 316 /// If you have an executable that is in a bundle and want to get 317 /// back to the bundle directory from the path itself, this 318 /// function will change a path to a file within a bundle to the 319 /// bundle directory itself. 320 /// 321 /// @param[in] file 322 /// A file spec that might point to a file in a bundle. 323 /// 324 /// @param[out] bundle_directory 325 /// An object will be filled in with the bundle directory for 326 /// the bundle when \b true is returned. Otherwise \a file is 327 /// left untouched and \b false is returned. 328 /// 329 /// @return 330 /// \b true if \a file was resolved in \a bundle_directory, 331 /// \b false otherwise. 332 //------------------------------------------------------------------ 333 static bool 334 GetBundleDirectory (const FileSpec &file, FileSpec &bundle_directory); 335 336 //------------------------------------------------------------------ 337 /// When executable files may live within a directory, where the 338 /// directory represents an executable bundle (like the MacOSX 339 /// app bundles), the locate the executable within the containing 340 /// bundle. 341 /// 342 /// @param[in,out] file 343 /// A file spec that currently points to the bundle that will 344 /// be filled in with the executable path within the bundle 345 /// if \b true is returned. Otherwise \a file is left untouched. 346 /// 347 /// @return 348 /// \b true if \a file was resolved, \b false if this function 349 /// was not able to resolve the path. 350 //------------------------------------------------------------------ 351 static bool 352 ResolveExecutableInBundle (FileSpec &file); 353 354 //------------------------------------------------------------------ 355 /// Find a resource files that are related to LLDB. 356 /// 357 /// Operating systems have different ways of storing shared 358 /// libraries and related resources. This function abstracts the 359 /// access to these paths. 360 /// 361 /// @param[in] path_type 362 /// The type of LLDB resource path you are looking for. If the 363 /// enumeration ends with "Dir", then only the \a file_spec's 364 /// directory member gets filled in. 365 /// 366 /// @param[in] file_spec 367 /// A file spec that gets filled in with the appriopriate path. 368 /// 369 /// @return 370 /// \b true if \a resource_path was resolved, \a false otherwise. 371 //------------------------------------------------------------------ 372 static bool 373 GetLLDBPath (PathType path_type, 374 FileSpec &file_spec); 375 376 //------------------------------------------------------------------ 377 /// Set a string that can be displayed if host application crashes. 378 /// 379 /// Some operating systems have the ability to print a description 380 /// for shared libraries when a program crashes. If the host OS 381 /// supports such a mechanism, it should be implemented to help 382 /// with crash triage. 383 /// 384 /// @param[in] format 385 /// A printf format that will be used to form a new crash 386 /// description string. 387 //------------------------------------------------------------------ 388 static void 389 SetCrashDescriptionWithFormat (const char *format, ...) __attribute__ ((format (printf, 1, 2))); 390 391 static void 392 SetCrashDescription (const char *description); 393 394 static uint32_t 395 FindProcesses (const ProcessInstanceInfoMatch &match_info, 396 ProcessInstanceInfoList &proc_infos); 397 398 static bool 399 GetProcessInfo (lldb::pid_t pid, ProcessInstanceInfo &proc_info); 400 401 static lldb::pid_t 402 LaunchApplication (const FileSpec &app_file_spec); 403 404 static Error 405 LaunchProcess (ProcessLaunchInfo &launch_info); 406 407 static lldb::DataBufferSP 408 GetAuxvData (lldb_private::Process *process); 409 410 static lldb::TargetSP 411 GetDummyTarget (Debugger &debugger); 412 413 static bool 414 OpenFileInExternalEditor (const FileSpec &file_spec, 415 uint32_t line_no); 416 417 static void 418 Backtrace (Stream &strm, uint32_t max_frames); 419 420 static size_t 421 GetEnvironment (StringList &env); 422 423 enum DynamicLibraryOpenOptions 424 { 425 eDynamicLibraryOpenOptionLazy = (1u << 0), // Lazily resolve symbols in this dynamic library 426 eDynamicLibraryOpenOptionLocal = (1u << 1), // Only open a shared library with local access (hide it from the global symbol namespace) 427 eDynamicLibraryOpenOptionLimitGetSymbol = (1u << 2) // DynamicLibraryGetSymbol calls on this handle will only return matches from this shared library 428 }; 429 static void * 430 DynamicLibraryOpen (const FileSpec &file_spec, 431 uint32_t options, 432 Error &error); 433 434 static Error 435 DynamicLibraryClose (void *dynamic_library_handle); 436 437 static void * 438 DynamicLibraryGetSymbol (void *dynamic_library_handle, 439 const char *symbol_name, 440 Error &error); 441}; 442 443} // namespace lldb_private 444 445#endif // #if defined(__cplusplus) 446#endif // liblldb_Host_h_ 447