contrib/llvm/tools/lldb/include/lldb/Host/Host.h

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