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