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     /// Gets the name of the distribution (i.e. distributor id).
 206     ///
 207     /// On Linux, this will return the equivalent of lsb_release -i.
 208     /// Android will return 'android'.  Other systems may return
 209     /// nothing.
 210     ///
 211     /// @return
 212     ///     A ConstString reference containing the OS distribution id.
 213     ///     The return string will be all lower case, with whitespace
 214     ///     replaced with underscores.  The return string will be
 215     ///     empty (result.AsCString() will return NULL) if the distribution
 216     ///     cannot be obtained.
 217     //------------------------------------------------------------------
 218     static const ConstString &
 219     GetDistributionId ();
 220
 221     //------------------------------------------------------------------
 222     /// Get the process ID for the calling process.
 223     ///
 224     /// @return
 225     ///     The process ID for the current process.
 226     //------------------------------------------------------------------
 227     static lldb::pid_t
 228     GetCurrentProcessID ();
 229
 230     static void
 231     Kill(lldb::pid_t pid, int signo);
 232
 233     //------------------------------------------------------------------
 234     /// Get the thread ID for the calling thread in the current process.
 235     ///
 236     /// @return
 237     ///     The thread ID for the calling thread in the current process.
 238     //------------------------------------------------------------------
 239     static lldb::tid_t
 240     GetCurrentThreadID ();
 241
 242     //------------------------------------------------------------------
 243     /// Get the thread token (the one returned by ThreadCreate when the thread was created) for the
 244     /// calling thread in the current process.
 245     ///
 246     /// @return
 247     ///     The thread token for the calling thread in the current process.
 248     //------------------------------------------------------------------
 249     static lldb::thread_t
 250     GetCurrentThread ();
 251
 252     static const char *
 253     GetSignalAsCString (int signo);
 254
 255     static void
 256     WillTerminate ();
 257     //------------------------------------------------------------------
 258     /// Host specific thread created function call.
 259     ///
 260     /// This function call lets the current host OS do any thread
 261     /// specific initialization that it needs, including naming the
 262     /// thread. No cleanup routine is exptected to be called
 263     ///
 264     /// @param[in] name
 265     ///     The current thread's name in the current process.
 266     //------------------------------------------------------------------
 267     static void
 268     ThreadCreated (const char *name);
 269
 270     static lldb::thread_t
 271     ThreadCreate (const char *name,
 272                   lldb::thread_func_t function,
 273                   lldb::thread_arg_t thread_arg,
 274                   Error *err);
 275
 276     static bool
 277     ThreadCancel (lldb::thread_t thread,
 278                   Error *error);
 279
 280     static bool
 281     ThreadDetach (lldb::thread_t thread,
 282                   Error *error);
 283     static bool
 284     ThreadJoin (lldb::thread_t thread,
 285                 lldb::thread_result_t *thread_result_ptr,
 286                 Error *error);
 287
 288     typedef void (*ThreadLocalStorageCleanupCallback) (void *p);
 289
 290     static lldb::thread_key_t
 291     ThreadLocalStorageCreate(ThreadLocalStorageCleanupCallback callback);
 292
 293     static void*
 294     ThreadLocalStorageGet(lldb::thread_key_t key);
 295
 296     static void
 297     ThreadLocalStorageSet(lldb::thread_key_t key, void *value);
 298
 299     //------------------------------------------------------------------
 300     /// Gets the name of a thread in a process.
 301     ///
 302     /// This function will name a thread in a process using it's own
 303     /// thread name pool, and also will attempt to set a thread name
 304     /// using any supported host OS APIs.
 305     ///
 306     /// @param[in] pid
 307     ///     The process ID in which we are trying to get the name of
 308     ///     a thread.
 309     ///
 310     /// @param[in] tid
 311     ///     The thread ID for which we are trying retrieve the name of.
 312     ///
 313     /// @return
 314     ///     A std::string containing the thread name.
 315     //------------------------------------------------------------------
 316     static std::string
 317     GetThreadName (lldb::pid_t pid, lldb::tid_t tid);
 318
 319     //------------------------------------------------------------------
 320     /// Sets the name of a thread in the current process.
 321     ///
 322     /// @param[in] pid
 323     ///     The process ID in which we are trying to name a thread.
 324     ///
 325     /// @param[in] tid
 326     ///     The thread ID which we are trying to name.
 327     ///
 328     /// @param[in] name
 329     ///     The current thread's name in the current process to \a name.
 330     ///
 331     /// @return
 332     ///     \b true if the thread name was able to be set, \b false
 333     ///     otherwise.
 334     //------------------------------------------------------------------
 335     static bool
 336     SetThreadName (lldb::pid_t pid, lldb::tid_t tid, const char *name);
 337
 338     //------------------------------------------------------------------
 339     /// Sets a shortened name of a thread in the current process.
 340     ///
 341     /// @param[in] pid
 342     ///     The process ID in which we are trying to name a thread.
 343     ///
 344     /// @param[in] tid
 345     ///     The thread ID which we are trying to name.
 346     ///
 347     /// @param[in] name
 348     ///     The current thread's name in the current process to \a name.
 349     ///
 350     /// @param[in] len
 351     ///     The maximum length for the thread's shortened name.
 352     ///
 353     /// @return
 354     ///     \b true if the thread name was able to be set, \b false
 355     ///     otherwise.
 356     static bool
 357     SetShortThreadName (lldb::pid_t pid, lldb::tid_t tid, const char *name, size_t len);
 358
 359     //------------------------------------------------------------------
 360     /// Gets the FileSpec of the current process (the process that
 361     /// that is running the LLDB code).
 362     ///
 363     /// @return
 364     ///     \b A file spec with the program name.
 365     //------------------------------------------------------------------
 366     static FileSpec
 367     GetProgramFileSpec ();
 368
 369     //------------------------------------------------------------------
 370     /// Given an address in the current process (the process that
 371     /// is running the LLDB code), return the name of the module that
 372     /// it comes from. This can be useful when you need to know the
 373     /// path to the shared library that your code is running in for
 374     /// loading resources that are relative to your binary.
 375     ///
 376     /// @param[in] host_addr
 377     ///     The pointer to some code in the current process.
 378     ///
 379     /// @return
 380     ///     \b A file spec with the module that contains \a host_addr,
 381     ///     which may be invalid if \a host_addr doesn't fall into
 382     ///     any valid module address range.
 383     //------------------------------------------------------------------
 384     static FileSpec
 385     GetModuleFileSpecForHostAddress (const void *host_addr);
 386
 387
 388
 389     //------------------------------------------------------------------
 390     /// If you have an executable that is in a bundle and want to get
 391     /// back to the bundle directory from the path itself, this
 392     /// function will change a path to a file within a bundle to the
 393     /// bundle directory itself.
 394     ///
 395     /// @param[in] file
 396     ///     A file spec that might point to a file in a bundle.
 397     ///
 398     /// @param[out] bundle_directory
 399     ///     An object will be filled in with the bundle directory for
 400     ///     the bundle when \b true is returned. Otherwise \a file is
 401     ///     left untouched and \b false is returned.
 402     ///
 403     /// @return
 404     ///     \b true if \a file was resolved in \a bundle_directory,
 405     ///     \b false otherwise.
 406     //------------------------------------------------------------------
 407     static bool
 408     GetBundleDirectory (const FileSpec &file, FileSpec &bundle_directory);
 409
 410     //------------------------------------------------------------------
 411     /// When executable files may live within a directory, where the
 412     /// directory represents an executable bundle (like the MacOSX
 413     /// app bundles), the locate the executable within the containing
 414     /// bundle.
 415     ///
 416     /// @param[in,out] file
 417     ///     A file spec that currently points to the bundle that will
 418     ///     be filled in with the executable path within the bundle
 419     ///     if \b true is returned. Otherwise \a file is left untouched.
 420     ///
 421     /// @return
 422     ///     \b true if \a file was resolved, \b false if this function
 423     ///     was not able to resolve the path.
 424     //------------------------------------------------------------------
 425     static bool
 426     ResolveExecutableInBundle (FileSpec &file);
 427
 428     //------------------------------------------------------------------
 429     /// Find a resource files that are related to LLDB.
 430     ///
 431     /// Operating systems have different ways of storing shared
 432     /// libraries and related resources. This function abstracts the
 433     /// access to these paths.
 434     ///
 435     /// @param[in] path_type
 436     ///     The type of LLDB resource path you are looking for. If the
 437     ///     enumeration ends with "Dir", then only the \a file_spec's
 438     ///     directory member gets filled in.
 439     ///
 440     /// @param[in] file_spec
 441     ///     A file spec that gets filled in with the appriopriate path.
 442     ///
 443     /// @return
 444     ///     \b true if \a resource_path was resolved, \a false otherwise.
 445     //------------------------------------------------------------------
 446     static bool
 447     GetLLDBPath (PathType path_type,
 448                  FileSpec &file_spec);
 449
 450     //------------------------------------------------------------------
 451     /// Set a string that can be displayed if host application crashes.
 452     ///
 453     /// Some operating systems have the ability to print a description
 454     /// for shared libraries when a program crashes. If the host OS
 455     /// supports such a mechanism, it should be implemented to help
 456     /// with crash triage.
 457     ///
 458     /// @param[in] format
 459     ///     A printf format that will be used to form a new crash
 460     ///     description string.
 461     //------------------------------------------------------------------
 462     static void
 463     SetCrashDescriptionWithFormat (const char *format, ...)  __attribute__ ((format (printf, 1, 2)));
 464
 465     static void
 466     SetCrashDescription (const char *description);
 467
 468     static uint32_t
 469     FindProcesses (const ProcessInstanceInfoMatch &match_info,
 470                    ProcessInstanceInfoList &proc_infos);
 471
 472     typedef std::map<lldb::pid_t, bool> TidMap;
 473     typedef std::pair<lldb::pid_t, bool> TidPair;
 474     static bool
 475     FindProcessThreads (const lldb::pid_t pid, TidMap &tids_to_attach);
 476
 477     static bool
 478     GetProcessInfo (lldb::pid_t pid, ProcessInstanceInfo &proc_info);
 479
 480 #if defined (__APPLE__) || defined (__linux__) || defined (__FreeBSD__) || defined (__GLIBC__)
 481     static short
 482     GetPosixspawnFlags (ProcessLaunchInfo &launch_info);
 483
 484     static Error
 485     LaunchProcessPosixSpawn (const char *exe_path, ProcessLaunchInfo &launch_info, ::pid_t &pid);
 486 #endif
 487
 488     static lldb::pid_t
 489     LaunchApplication (const FileSpec &app_file_spec);
 490
 491     static Error
 492     LaunchProcess (ProcessLaunchInfo &launch_info);
 493
 494     static Error
 495     RunShellCommand (const char *command,           // Shouldn't be NULL
 496                      const char *working_dir,       // Pass NULL to use the current working directory
 497                      int *status_ptr,               // Pass NULL if you don't want the process exit status
 498                      int *signo_ptr,                // Pass NULL if you don't want the signal that caused the process to exit
 499                      std::string *command_output,   // Pass NULL if you don't want the command output
 500                      uint32_t timeout_sec,
 501                      const char *shell = LLDB_DEFAULT_SHELL);
 502
 503     static lldb::DataBufferSP
 504     GetAuxvData (lldb_private::Process *process);
 505
 506     static lldb::TargetSP
 507     GetDummyTarget (Debugger &debugger);
 508
 509     static bool
 510     OpenFileInExternalEditor (const FileSpec &file_spec,
 511                               uint32_t line_no);
 512
 513     static void
 514     Backtrace (Stream &strm, uint32_t max_frames);
 515
 516     static size_t
 517     GetEnvironment (StringList &env);
 518
 519     enum DynamicLibraryOpenOptions
 520     {
 521         eDynamicLibraryOpenOptionLazy           = (1u << 0),  // Lazily resolve symbols in this dynamic library
 522         eDynamicLibraryOpenOptionLocal          = (1u << 1),  // Only open a shared library with local access (hide it from the global symbol namespace)
 523         eDynamicLibraryOpenOptionLimitGetSymbol = (1u << 2)   // DynamicLibraryGetSymbol calls on this handle will only return matches from this shared library
 524     };
 525     static void *
 526     DynamicLibraryOpen (const FileSpec &file_spec,
 527                         uint32_t options,
 528                         Error &error);
 529
 530     static Error
 531     DynamicLibraryClose (void *dynamic_library_handle);
 532
 533     static void *
 534     DynamicLibraryGetSymbol (void *dynamic_library_handle,
 535                              const char *symbol_name,
 536                              Error &error);
 537
 538     static Error
 539     MakeDirectory (const char* path, uint32_t mode);
 540
 541     static Error
 542     GetFilePermissions (const char* path, uint32_t &file_permissions);
 543
 544     static Error
 545     SetFilePermissions (const char* path, uint32_t file_permissions);
 546
 547     static Error
 548     Symlink (const char *src, const char *dst);
 549
 550     static Error
 551     Readlink (const char *path, char *buf, size_t buf_len);
 552
 553     static Error
 554     Unlink (const char *path);
 555
 556     static lldb::user_id_t
 557     OpenFile (const FileSpec& file_spec,
 558               uint32_t flags,
 559               uint32_t mode,
 560               Error &error);
 561
 562     static bool
 563     CloseFile (lldb::user_id_t fd,
 564                Error &error);
 565
 566     static uint64_t
 567     WriteFile (lldb::user_id_t fd,
 568                uint64_t offset,
 569                const void* src,
 570                uint64_t src_len,
 571                Error &error);
 572
 573     static uint64_t
 574     ReadFile (lldb::user_id_t fd,
 575               uint64_t offset,
 576               void* dst,
 577               uint64_t dst_len,
 578               Error &error);
 579
 580     static lldb::user_id_t
 581     GetFileSize (const FileSpec& file_spec);
 582
 583     static bool
 584     GetFileExists (const FileSpec& file_spec);
 585
 586     static bool
 587     CalculateMD5 (const FileSpec& file_spec,
 588                   uint64_t &low,
 589                   uint64_t &high);
 590
 591 };
 592
 593 } // namespace lldb_private
 594
 595 #endif  // #if defined(__cplusplus)
 596 #endif  // liblldb_Host_h_