Host.h revision 24943d2ee8bfaa7cf5893e4709143924157a5c1e
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 17namespace lldb_private { 18 19//---------------------------------------------------------------------- 20/// @class Host Host.h "lldb/Host/Host.h" 21/// @brief A class that provides host computer information. 22/// 23/// Host is a class that answers information about the host operating 24/// system. 25//---------------------------------------------------------------------- 26class Host 27{ 28public: 29 typedef bool (*MonitorChildProcessCallback) (void *callback_baton, 30 lldb::pid_t pid, 31 int signal, // Zero for no signal 32 int status); // Exit value of process if signal is zero 33 34 //------------------------------------------------------------------ 35 /// Start monitoring a child process. 36 /// 37 /// Allows easy monitoring of child processes. \a callback will be 38 /// called when the child process exits or if it gets a signal. The 39 /// callback will only be called with signals if \a monitor_signals 40 /// is \b true. \a callback will usually be called from another 41 /// thread so the callback function must be thread safe. 42 /// 43 /// When the callback gets called, the return value indicates if 44 /// minotoring should stop. If \b true is returned from \a callback 45 /// the information will be removed. If \b false is returned then 46 /// monitoring will continue. If the child process exits, the 47 /// monitoring will automatically stop after the callback returned 48 /// ragardless of the callback return value. 49 /// 50 /// @param[in] callback 51 /// A function callback to call when a child receives a signal 52 /// (if \a monitor_signals is true) or a child exits. 53 /// 54 /// @param[in] callback_baton 55 /// A void * of user data that will be pass back when 56 /// \a callback is called. 57 /// 58 /// @param[in] pid 59 /// The process ID of a child process to monitor, -1 for all 60 /// processes. 61 /// 62 /// @param[in] monitor_signals 63 /// If \b true the callback will get called when the child 64 /// process gets a signal. If \b false, the callback will only 65 /// get called if the child process exits. 66 /// 67 /// @return 68 /// A unique handle to the process monitoring information that 69 /// can be used to stop monitoring a child process. 70 /// 71 /// @see static void Host::StopMonitoringChildProcess (uint32_t) 72 //------------------------------------------------------------------ 73 static uint32_t 74 StartMonitoringChildProcess (MonitorChildProcessCallback callback, 75 void *callback_baton, 76 lldb::pid_t pid, 77 bool monitor_signals); 78 79 //------------------------------------------------------------------ 80 /// Stop monitoring a child process. 81 /// 82 /// @param[in] handle 83 /// A unique handle returned from a previous call to 84 /// Host::StartMonitoringChildProcess(...). 85 /// 86 /// @return 87 /// \b true if the the handle was found and disabled, \b false 88 /// if the monitor map with handle of \a handle was not found. 89 /// 90 /// @see static int Host::StartMonitoringChildProcess (MonitorChildProcessCallback *, void *, lldb::pid_t, bool) 91 //------------------------------------------------------------------ 92 static bool 93 StopMonitoringChildProcess (uint32_t handle); 94 95 //------------------------------------------------------------------ 96 /// Get the host page size. 97 /// 98 /// @return 99 /// The size in bytes of a VM page on the host system. 100 //------------------------------------------------------------------ 101 static size_t 102 GetPageSize(); 103 104 //------------------------------------------------------------------ 105 /// Returns the endianness of the host system. 106 /// 107 /// @return 108 /// Returns the endianness of the host system as a lldb::ByteOrder 109 /// enumeration. 110 //------------------------------------------------------------------ 111 static lldb::ByteOrder 112 GetByteOrder (); 113 114 //------------------------------------------------------------------ 115 /// Gets the host kernel architecture. 116 /// 117 /// @return 118 /// A const architecture object that represents the host kernel 119 /// architecture. 120 //------------------------------------------------------------------ 121 static const ArchSpec & 122 GetArchitecture (); 123 124 //------------------------------------------------------------------ 125 /// Gets the host vendor string. 126 /// 127 /// @return 128 /// A const string object containing the host vendor name. 129 //------------------------------------------------------------------ 130 static const ConstString & 131 GetVendorString (); 132 133 //------------------------------------------------------------------ 134 /// Gets the host Operating System (OS) string. 135 /// 136 /// @return 137 /// A const string object containing the host OS name. 138 //------------------------------------------------------------------ 139 static const ConstString & 140 GetOSString (); 141 142 //------------------------------------------------------------------ 143 /// Gets the host target triple as a const string. 144 /// 145 /// @return 146 /// A const string object containing the host target triple. 147 //------------------------------------------------------------------ 148 static const ConstString & 149 GetTargetTriple (); 150 151 //------------------------------------------------------------------ 152 /// Get the process ID for the calling process. 153 /// 154 /// @return 155 /// The process ID for the current process. 156 //------------------------------------------------------------------ 157 static lldb::pid_t 158 GetCurrentProcessID (); 159 160 //------------------------------------------------------------------ 161 /// Get the thread ID for the calling thread in the current process. 162 /// 163 /// @return 164 /// The thread ID for the calling thread in the current process. 165 //------------------------------------------------------------------ 166 static lldb::pid_t 167 GetCurrentThreadID (); 168 169 static const char * 170 GetSignalAsCString (int signo); 171 172 static void 173 WillTerminate (); 174 //------------------------------------------------------------------ 175 /// Host specific thread created function call. 176 /// 177 /// This function call lets the current host OS do any thread 178 /// specific initialization that it needs, including naming the 179 /// thread. No cleanup routine is exptected to be called 180 /// 181 /// @param[in] name 182 /// The current thread's name in the current process. 183 //------------------------------------------------------------------ 184 static void 185 ThreadCreated (const char *name); 186 187 static lldb::thread_t 188 ThreadCreate (const char *name, 189 lldb::thread_func_t function, 190 lldb::thread_arg_t thread_arg, 191 Error *err); 192 193 static bool 194 ThreadCancel (lldb::thread_t thread, 195 Error *error); 196 197 static bool 198 ThreadDetach (lldb::thread_t thread, 199 Error *error); 200 static bool 201 ThreadJoin (lldb::thread_t thread, 202 lldb::thread_result_t *thread_result_ptr, 203 Error *error); 204 205 //------------------------------------------------------------------ 206 /// Gets the name of a thread in a process. 207 /// 208 /// This function will name a thread in a process using it's own 209 /// thread name pool, and also will attempt to set a thread name 210 /// using any supported host OS APIs. 211 /// 212 /// @param[in] pid 213 /// The process ID in which we are trying to get the name of 214 /// a thread. 215 /// 216 /// @param[in] tid 217 /// The thread ID for which we are trying retrieve the name of. 218 /// 219 /// @return 220 /// A NULL terminate C string name that is owned by a static 221 /// global string pool, or NULL if there is no matching thread 222 /// name. This string does not need to be freed. 223 //------------------------------------------------------------------ 224 static const char * 225 GetThreadName (lldb::pid_t pid, lldb::tid_t tid); 226 227 //------------------------------------------------------------------ 228 /// Sets the name of a thread in the current process. 229 /// 230 /// @param[in] pid 231 /// The process ID in which we are trying to name a thread. 232 /// 233 /// @param[in] tid 234 /// The thread ID which we are trying to name. 235 /// 236 /// @param[in] name 237 /// The current thread's name in the current process to \a name. 238 /// 239 /// @return 240 /// \b true if the thread name was able to be set, \b false 241 /// otherwise. 242 //------------------------------------------------------------------ 243 static void 244 SetThreadName (lldb::pid_t pid, lldb::tid_t tid, const char *name); 245 246 //------------------------------------------------------------------ 247 /// Gets the FileSpec of the current process (the process that 248 /// that is running the LLDB code). 249 /// 250 /// @return 251 /// \b A file spec with the program name. 252 //------------------------------------------------------------------ 253 static FileSpec 254 GetProgramFileSpec (); 255 256 //------------------------------------------------------------------ 257 /// Given an address in the current process (the process that 258 /// is running the LLDB code), return the name of the module that 259 /// it comes from. This can be useful when you need to know the 260 /// path to the shared library that your code is running in for 261 /// loading resources that are relative to your binary. 262 /// 263 /// @param[in] host_addr 264 /// The pointer to some code in the current process. 265 /// 266 /// @return 267 /// \b A file spec with the module that contains \a host_addr, 268 /// which may be invalid if \a host_addr doesn't fall into 269 /// any valid module address range. 270 //------------------------------------------------------------------ 271 static FileSpec 272 GetModuleFileSpecForHostAddress (const void *host_addr); 273 274 static bool 275 ResolveExecutableInBundle (FileSpec *file); 276}; 277 278} // namespace lldb_private 279 280#endif // #if defined(__cplusplus) 281#endif // liblldb_Host_h_ 282