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