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/lldb-private-forward.h"
  21 #include "lldb/Core/StringList.h"
  22 #include "lldb/Host/File.h"
  23 #include "lldb/Host/FileSpec.h"
  24
  25 namespace lldb_private {
  26
  27 class FileAction;
  28 class ProcessLaunchInfo;
  29
  30 //----------------------------------------------------------------------
  31 /// @class Host Host.h "lldb/Host/Host.h"
  32 /// @brief A class that provides host computer information.
  33 ///
  34 /// Host is a class that answers information about the host operating
  35 /// system.
  36 //----------------------------------------------------------------------
  37 class Host
  38 {
  39 public:
  40
  41     /// A value of std::numeric_limits<uint32_t>::max() is used if there is no practical limit.
  42     static const uint32_t MAX_THREAD_NAME_LENGTH;
  43
  44     typedef bool (*MonitorChildProcessCallback) (void *callback_baton,
  45                                                  lldb::pid_t pid,
  46                                                  bool exited,
  47                                                  int signal,    // Zero for no signal
  48                                                  int status);   // Exit value of process if signal is zero
  49
  50     //------------------------------------------------------------------
  51     /// Start monitoring a child process.
  52     ///
  53     /// Allows easy monitoring of child processes. \a callback will be
  54     /// called when the child process exits or if it gets a signal. The
  55     /// callback will only be called with signals if \a monitor_signals
  56     /// is \b true. \a callback will usually be called from another
  57     /// thread so the callback function must be thread safe.
  58     ///
  59     /// When the callback gets called, the return value indicates if
  60     /// monitoring should stop. If \b true is returned from \a callback
  61     /// the information will be removed. If \b false is returned then
  62     /// monitoring will continue. If the child process exits, the
  63     /// monitoring will automatically stop after the callback returned
  64     /// regardless of the callback return value.
  65     ///
  66     /// @param[in] callback
  67     ///     A function callback to call when a child receives a signal
  68     ///     (if \a monitor_signals is true) or a child exits.
  69     ///
  70     /// @param[in] callback_baton
  71     ///     A void * of user data that will be pass back when
  72     ///     \a callback is called.
  73     ///
  74     /// @param[in] pid
  75     ///     The process ID of a child process to monitor, -1 for all
  76     ///     processes.
  77     ///
  78     /// @param[in] monitor_signals
  79     ///     If \b true the callback will get called when the child
  80     ///     process gets a signal. If \b false, the callback will only
  81     ///     get called if the child process exits.
  82     ///
  83     /// @return
  84     ///     A thread handle that can be used to cancel the thread that
  85     ///     was spawned to monitor \a pid.
  86     ///
  87     /// @see static void Host::StopMonitoringChildProcess (uint32_t)
  88     //------------------------------------------------------------------
  89     static lldb::thread_t
  90     StartMonitoringChildProcess (MonitorChildProcessCallback callback,
  91                                  void *callback_baton,
  92                                  lldb::pid_t pid,
  93                                  bool monitor_signals);
  94
  95     enum SystemLogType
  96     {
  97         eSystemLogWarning,
  98         eSystemLogError
  99     };
 100
 101     static void
 102     SystemLog (SystemLogType type, const char *format, ...) __attribute__ ((format (printf, 2, 3)));
 103
 104     static void
 105     SystemLog (SystemLogType type, const char *format, va_list args);
 106
 107     //------------------------------------------------------------------
 108     /// Get the process ID for the calling process.
 109     ///
 110     /// @return
 111     ///     The process ID for the current process.
 112     //------------------------------------------------------------------
 113     static lldb::pid_t
 114     GetCurrentProcessID ();
 115
 116     static void
 117     Kill(lldb::pid_t pid, int signo);
 118
 119     //------------------------------------------------------------------
 120     /// Get the thread ID for the calling thread in the current process.
 121     ///
 122     /// @return
 123     ///     The thread ID for the calling thread in the current process.
 124     //------------------------------------------------------------------
 125     static lldb::tid_t
 126     GetCurrentThreadID ();
 127
 128     //------------------------------------------------------------------
 129     /// Get the thread token (the one returned by ThreadCreate when the thread was created) for the
 130     /// calling thread in the current process.
 131     ///
 132     /// @return
 133     ///     The thread token for the calling thread in the current process.
 134     //------------------------------------------------------------------
 135     static lldb::thread_t
 136     GetCurrentThread ();
 137
 138     static const char *
 139     GetSignalAsCString (int signo);
 140
 141     static void
 142     WillTerminate ();
 143     //------------------------------------------------------------------
 144     /// Host specific thread created function call.
 145     ///
 146     /// This function call lets the current host OS do any thread
 147     /// specific initialization that it needs, including naming the
 148     /// thread. No cleanup routine is expected to be called
 149     ///
 150     /// @param[in] name
 151     ///     The current thread's name in the current process.
 152     //------------------------------------------------------------------
 153     static void
 154     ThreadCreated (const char *name);
 155
 156     static lldb::thread_t
 157     ThreadCreate (const char *name,
 158                   lldb::thread_func_t function,
 159                   lldb::thread_arg_t thread_arg,
 160                   Error *err);
 161
 162     static bool
 163     ThreadCancel (lldb::thread_t thread,
 164                   Error *error);
 165
 166     static bool
 167     ThreadDetach (lldb::thread_t thread,
 168                   Error *error);
 169     static bool
 170     ThreadJoin (lldb::thread_t thread,
 171                 lldb::thread_result_t *thread_result_ptr,
 172                 Error *error);
 173
 174     typedef void (*ThreadLocalStorageCleanupCallback) (void *p);
 175
 176     static lldb::thread_key_t
 177     ThreadLocalStorageCreate(ThreadLocalStorageCleanupCallback callback);
 178
 179     static void*
 180     ThreadLocalStorageGet(lldb::thread_key_t key);
 181
 182     static void
 183     ThreadLocalStorageSet(lldb::thread_key_t key, void *value);
 184
 185     //------------------------------------------------------------------
 186     /// Gets the name of a thread in a process.
 187     ///
 188     /// This function will name a thread in a process using it's own
 189     /// thread name pool, and also will attempt to set a thread name
 190     /// using any supported host OS APIs.
 191     ///
 192     /// @param[in] pid
 193     ///     The process ID in which we are trying to get the name of
 194     ///     a thread.
 195     ///
 196     /// @param[in] tid
 197     ///     The thread ID for which we are trying retrieve the name of.
 198     ///
 199     /// @return
 200     ///     A std::string containing the thread name.
 201     //------------------------------------------------------------------
 202     static std::string
 203     GetThreadName (lldb::pid_t pid, lldb::tid_t tid);
 204
 205     //------------------------------------------------------------------
 206     /// Sets the name of a thread in the current process.
 207     ///
 208     /// @param[in] pid
 209     ///     The process ID in which we are trying to name a thread.
 210     ///
 211     /// @param[in] tid
 212     ///     The thread ID which we are trying to name.
 213     ///
 214     /// @param[in] name
 215     ///     The current thread's name in the current process to \a name.
 216     ///
 217     /// @return
 218     ///     \b true if the thread name was able to be set, \b false
 219     ///     otherwise.
 220     //------------------------------------------------------------------
 221     static bool
 222     SetThreadName (lldb::pid_t pid, lldb::tid_t tid, const char *name);
 223
 224     //------------------------------------------------------------------
 225     /// Sets a shortened name of a thread in the current process.
 226     ///
 227     /// @param[in] pid
 228     ///     The process ID in which we are trying to name a thread.
 229     ///
 230     /// @param[in] tid
 231     ///     The thread ID which we are trying to name.
 232     ///
 233     /// @param[in] name
 234     ///     The current thread's name in the current process to \a name.
 235     ///
 236     /// @param[in] len
 237     ///     The maximum length for the thread's shortened name.
 238     ///
 239     /// @return
 240     ///     \b true if the thread name was able to be set, \b false
 241     ///     otherwise.
 242     static bool
 243     SetShortThreadName (lldb::pid_t pid, lldb::tid_t tid, const char *name, size_t len);
 244
 245     //------------------------------------------------------------------
 246     /// Given an address in the current process (the process that
 247     /// is running the LLDB code), return the name of the module that
 248     /// it comes from. This can be useful when you need to know the
 249     /// path to the shared library that your code is running in for
 250     /// loading resources that are relative to your binary.
 251     ///
 252     /// @param[in] host_addr
 253     ///     The pointer to some code in the current process.
 254     ///
 255     /// @return
 256     ///     \b A file spec with the module that contains \a host_addr,
 257     ///     which may be invalid if \a host_addr doesn't fall into
 258     ///     any valid module address range.
 259     //------------------------------------------------------------------
 260     static FileSpec
 261     GetModuleFileSpecForHostAddress (const void *host_addr);
 262
 263     //------------------------------------------------------------------
 264     /// If you have an executable that is in a bundle and want to get
 265     /// back to the bundle directory from the path itself, this
 266     /// function will change a path to a file within a bundle to the
 267     /// bundle directory itself.
 268     ///
 269     /// @param[in] file
 270     ///     A file spec that might point to a file in a bundle.
 271     ///
 272     /// @param[out] bundle_directory
 273     ///     An object will be filled in with the bundle directory for
 274     ///     the bundle when \b true is returned. Otherwise \a file is
 275     ///     left untouched and \b false is returned.
 276     ///
 277     /// @return
 278     ///     \b true if \a file was resolved in \a bundle_directory,
 279     ///     \b false otherwise.
 280     //------------------------------------------------------------------
 281     static bool
 282     GetBundleDirectory (const FileSpec &file, FileSpec &bundle_directory);
 283
 284     //------------------------------------------------------------------
 285     /// When executable files may live within a directory, where the
 286     /// directory represents an executable bundle (like the MacOSX
 287     /// app bundles), then locate the executable within the containing
 288     /// bundle.
 289     ///
 290     /// @param[in,out] file
 291     ///     A file spec that currently points to the bundle that will
 292     ///     be filled in with the executable path within the bundle
 293     ///     if \b true is returned. Otherwise \a file is left untouched.
 294     ///
 295     /// @return
 296     ///     \b true if \a file was resolved, \b false if this function
 297     ///     was not able to resolve the path.
 298     //------------------------------------------------------------------
 299     static bool
 300     ResolveExecutableInBundle (FileSpec &file);
 301
 302     //------------------------------------------------------------------
 303     /// Set a string that can be displayed if host application crashes.
 304     ///
 305     /// Some operating systems have the ability to print a description
 306     /// for shared libraries when a program crashes. If the host OS
 307     /// supports such a mechanism, it should be implemented to help
 308     /// with crash triage.
 309     ///
 310     /// @param[in] format
 311     ///     A printf format that will be used to form a new crash
 312     ///     description string.
 313     //------------------------------------------------------------------
 314     static void
 315     SetCrashDescriptionWithFormat (const char *format, ...)  __attribute__ ((format (printf, 1, 2)));
 316
 317     static void
 318     SetCrashDescription (const char *description);
 319
 320     static uint32_t
 321     FindProcesses (const ProcessInstanceInfoMatch &match_info,
 322                    ProcessInstanceInfoList &proc_infos);
 323
 324     typedef std::map<lldb::pid_t, bool> TidMap;
 325     typedef std::pair<lldb::pid_t, bool> TidPair;
 326     static bool
 327     FindProcessThreads (const lldb::pid_t pid, TidMap &tids_to_attach);
 328
 329     static bool
 330     GetProcessInfo (lldb::pid_t pid, ProcessInstanceInfo &proc_info);
 331
 332 #if defined (__APPLE__) || defined (__linux__) || defined (__FreeBSD__) || defined (__GLIBC__) || defined (__NetBSD__)
 333     static short
 334     GetPosixspawnFlags (ProcessLaunchInfo &launch_info);
 335
 336     static Error
 337     LaunchProcessPosixSpawn (const char *exe_path, ProcessLaunchInfo &launch_info, ::pid_t &pid);
 338
 339     static bool AddPosixSpawnFileAction(void *file_actions, const FileAction *info, Log *log, Error &error);
 340 #endif
 341
 342     static const lldb_private::UnixSignalsSP&
 343     GetUnixSignals ();
 344
 345     static lldb::pid_t
 346     LaunchApplication (const FileSpec &app_file_spec);
 347
 348     static Error
 349     LaunchProcess (ProcessLaunchInfo &launch_info);
 350
 351     static Error
 352     RunShellCommand (const char *command,           // Shouldn't be NULL
 353                      const char *working_dir,       // Pass NULL to use the current working directory
 354                      int *status_ptr,               // Pass NULL if you don't want the process exit status
 355                      int *signo_ptr,                // Pass NULL if you don't want the signal that caused the process to exit
 356                      std::string *command_output,   // Pass NULL if you don't want the command output
 357                      uint32_t timeout_sec,
 358                      const char *shell = LLDB_DEFAULT_SHELL);
 359
 360     static lldb::DataBufferSP
 361     GetAuxvData (lldb_private::Process *process);
 362
 363     static lldb::DataBufferSP
 364     GetAuxvData (lldb::pid_t pid);
 365
 366     static lldb::TargetSP
 367     GetDummyTarget (Debugger &debugger);
 368
 369     static bool
 370     OpenFileInExternalEditor (const FileSpec &file_spec,
 371                               uint32_t line_no);
 372
 373     static void
 374     Backtrace (Stream &strm, uint32_t max_frames);
 375
 376     static size_t
 377     GetEnvironment (StringList &env);
 378 };
 379
 380 } // namespace lldb_private
 381
 382 #endif  // #if defined(__cplusplus)
 383 #endif  // liblldb_Host_h_