1 //===-- SBAttachInfo.h ------------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLDB_API_SBATTACHINFO_H 10 #define LLDB_API_SBATTACHINFO_H 11 12 #include "lldb/API/SBDefines.h" 13 14 namespace lldb_private { 15 class ScriptInterpreter; 16 } 17 18 namespace lldb { 19 20 class SBTarget; 21 22 class LLDB_API SBAttachInfo { 23 public: 24 SBAttachInfo(); 25 26 SBAttachInfo(lldb::pid_t pid); 27 28 /// Attach to a process by name. 29 /// 30 /// This function implies that a future call to SBTarget::Attach(...) 31 /// will be synchronous. 32 /// 33 /// \param[in] path 34 /// A full or partial name for the process to attach to. 35 /// 36 /// \param[in] wait_for 37 /// If \b false, attach to an existing process whose name matches. 38 /// If \b true, then wait for the next process whose name matches. 39 SBAttachInfo(const char *path, bool wait_for); 40 41 /// Attach to a process by name. 42 /// 43 /// Future calls to SBTarget::Attach(...) will be synchronous or 44 /// asynchronous depending on the \a async argument. 45 /// 46 /// \param[in] path 47 /// A full or partial name for the process to attach to. 48 /// 49 /// \param[in] wait_for 50 /// If \b false, attach to an existing process whose name matches. 51 /// If \b true, then wait for the next process whose name matches. 52 /// 53 /// \param[in] async 54 /// If \b false, then the SBTarget::Attach(...) call will be a 55 /// synchronous call with no way to cancel the attach in 56 /// progress. 57 /// If \b true, then the SBTarget::Attach(...) function will 58 /// return immediately and clients are expected to wait for a 59 /// process eStateStopped event if a suitable process is 60 /// eventually found. If the client wants to cancel the event, 61 /// SBProcess::Stop() can be called and an eStateExited process 62 /// event will be delivered. 63 SBAttachInfo(const char *path, bool wait_for, bool async); 64 65 SBAttachInfo(const SBAttachInfo &rhs); 66 67 ~SBAttachInfo(); 68 69 SBAttachInfo &operator=(const SBAttachInfo &rhs); 70 71 lldb::pid_t GetProcessID(); 72 73 void SetProcessID(lldb::pid_t pid); 74 75 void SetExecutable(const char *path); 76 77 void SetExecutable(lldb::SBFileSpec exe_file); 78 79 bool GetWaitForLaunch(); 80 81 /// Set attach by process name settings. 82 /// 83 /// Designed to be used after a call to SBAttachInfo::SetExecutable(). 84 /// This function implies that a call to SBTarget::Attach(...) will 85 /// be synchronous. 86 /// 87 /// \param[in] b 88 /// If \b false, attach to an existing process whose name matches. 89 /// If \b true, then wait for the next process whose name matches. 90 void SetWaitForLaunch(bool b); 91 92 /// Set attach by process name settings. 93 /// 94 /// Designed to be used after a call to SBAttachInfo::SetExecutable(). 95 /// Future calls to SBTarget::Attach(...) will be synchronous or 96 /// asynchronous depending on the \a async argument. 97 /// 98 /// \param[in] b 99 /// If \b false, attach to an existing process whose name matches. 100 /// If \b true, then wait for the next process whose name matches. 101 /// 102 /// \param[in] async 103 /// If \b false, then the SBTarget::Attach(...) call will be a 104 /// synchronous call with no way to cancel the attach in 105 /// progress. 106 /// If \b true, then the SBTarget::Attach(...) function will 107 /// return immediately and clients are expected to wait for a 108 /// process eStateStopped event if a suitable process is 109 /// eventually found. If the client wants to cancel the event, 110 /// SBProcess::Stop() can be called and an eStateExited process 111 /// event will be delivered. 112 void SetWaitForLaunch(bool b, bool async); 113 114 bool GetIgnoreExisting(); 115 116 void SetIgnoreExisting(bool b); 117 118 uint32_t GetResumeCount(); 119 120 void SetResumeCount(uint32_t c); 121 122 const char *GetProcessPluginName(); 123 124 void SetProcessPluginName(const char *plugin_name); 125 126 uint32_t GetUserID(); 127 128 uint32_t GetGroupID(); 129 130 bool UserIDIsValid(); 131 132 bool GroupIDIsValid(); 133 134 void SetUserID(uint32_t uid); 135 136 void SetGroupID(uint32_t gid); 137 138 uint32_t GetEffectiveUserID(); 139 140 uint32_t GetEffectiveGroupID(); 141 142 bool EffectiveUserIDIsValid(); 143 144 bool EffectiveGroupIDIsValid(); 145 146 void SetEffectiveUserID(uint32_t uid); 147 148 void SetEffectiveGroupID(uint32_t gid); 149 150 lldb::pid_t GetParentProcessID(); 151 152 void SetParentProcessID(lldb::pid_t pid); 153 154 bool ParentProcessIDIsValid(); 155 156 /// Get the listener that will be used to receive process events. 157 /// 158 /// If no listener has been set via a call to 159 /// SBAttachInfo::SetListener(), then an invalid SBListener will be 160 /// returned (SBListener::IsValid() will return false). If a listener 161 /// has been set, then the valid listener object will be returned. 162 SBListener GetListener(); 163 164 /// Set the listener that will be used to receive process events. 165 /// 166 /// By default the SBDebugger, which has a listener, that the SBTarget 167 /// belongs to will listen for the process events. Calling this function 168 /// allows a different listener to be used to listen for process events. 169 void SetListener(SBListener &listener); 170 171 /// Get the shadow listener that receive public process events, 172 /// additionally to the default process event listener. 173 /// 174 /// If no listener has been set via a call to 175 /// SBLaunchInfo::SetShadowListener(), then an invalid SBListener will 176 /// be returned (SBListener::IsValid() will return false). If a listener 177 /// has been set, then the valid listener object will be returned. 178 SBListener GetShadowListener(); 179 180 /// Set the shadow listener that will receive public process events, 181 /// additionally to the default process event listener. 182 /// 183 /// By default a process have no shadow event listener. 184 /// Calling this function allows public process events to be broadcasted to an 185 /// additional listener on top of the default process event listener. 186 /// If the `listener` argument is invalid (SBListener::IsValid() will 187 /// return false), this will clear the shadow listener. 188 void SetShadowListener(SBListener &listener); 189 190 const char *GetScriptedProcessClassName() const; 191 192 void SetScriptedProcessClassName(const char *class_name); 193 194 lldb::SBStructuredData GetScriptedProcessDictionary() const; 195 196 void SetScriptedProcessDictionary(lldb::SBStructuredData dict); 197 198 protected: 199 friend class SBTarget; 200 friend class SBPlatform; 201 202 friend class lldb_private::ScriptInterpreter; 203 204 lldb_private::ProcessAttachInfo &ref(); 205 206 ProcessAttachInfoSP m_opaque_sp; 207 }; 208 209 } // namespace lldb 210 211 #endif // LLDB_API_SBATTACHINFO_H 212