1 //===-- SBLaunchInfo.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_SBLAUNCHINFO_H 10 #define LLDB_API_SBLAUNCHINFO_H 11 12 #include "lldb/API/SBDefines.h" 13 14 namespace lldb_private { 15 class SBLaunchInfoImpl; 16 class ScriptInterpreter; 17 } 18 19 namespace lldb { 20 21 class SBPlatform; 22 class SBTarget; 23 24 class LLDB_API SBLaunchInfo { 25 public: 26 SBLaunchInfo(const char **argv); 27 28 ~SBLaunchInfo(); 29 30 #ifndef SWIG 31 // The copy constructor for SBLaunchInfo presents some problems on some 32 // supported versions of swig (e.g. 3.0.2). When trying to create an 33 // SBLaunchInfo from python with the argument `None`, swig will try to call 34 // the copy constructor instead of SBLaunchInfo(const char **). For that 35 // reason, we avoid exposing the copy constructor to python. 36 SBLaunchInfo(const SBLaunchInfo &rhs); 37 #endif 38 39 SBLaunchInfo &operator=(const SBLaunchInfo &rhs); 40 41 lldb::pid_t GetProcessID(); 42 43 uint32_t GetUserID(); 44 45 uint32_t GetGroupID(); 46 47 bool UserIDIsValid(); 48 49 bool GroupIDIsValid(); 50 51 void SetUserID(uint32_t uid); 52 53 void SetGroupID(uint32_t gid); 54 55 SBFileSpec GetExecutableFile(); 56 57 /// Set the executable file that will be used to launch the process and 58 /// optionally set it as the first argument in the argument vector. 59 /// 60 /// This only needs to be specified if clients wish to carefully control 61 /// the exact path will be used to launch a binary. If you create a 62 /// target with a symlink, that symlink will get resolved in the target 63 /// and the resolved path will get used to launch the process. Calling 64 /// this function can help you still launch your process using the 65 /// path of your choice. 66 /// 67 /// If this function is not called prior to launching with 68 /// SBTarget::Launch(...), the target will use the resolved executable 69 /// path that was used to create the target. 70 /// 71 /// \param[in] exe_file 72 /// The override path to use when launching the executable. 73 /// 74 /// \param[in] add_as_first_arg 75 /// If true, then the path will be inserted into the argument vector 76 /// prior to launching. Otherwise the argument vector will be left 77 /// alone. 78 void SetExecutableFile(SBFileSpec exe_file, bool add_as_first_arg); 79 80 /// Get the listener that will be used to receive process events. 81 /// 82 /// If no listener has been set via a call to 83 /// SBLaunchInfo::SetListener(), then an invalid SBListener will be 84 /// returned (SBListener::IsValid() will return false). If a listener 85 /// has been set, then the valid listener object will be returned. 86 SBListener GetListener(); 87 88 /// Set the listener that will be used to receive process events. 89 /// 90 /// By default the SBDebugger, which has a listener, that the SBTarget 91 /// belongs to will listen for the process events. Calling this function 92 /// allows a different listener to be used to listen for process events. 93 void SetListener(SBListener &listener); 94 95 /// Get the shadow listener that receive public process events, 96 /// additionally to the default process event listener. 97 /// 98 /// If no listener has been set via a call to 99 /// SBLaunchInfo::SetShadowListener(), then an invalid SBListener will 100 /// be returned (SBListener::IsValid() will return false). If a listener 101 /// has been set, then the valid listener object will be returned. 102 SBListener GetShadowListener(); 103 104 /// Set the shadow listener that will receive public process events, 105 /// additionally to the default process event listener. 106 /// 107 /// By default a process have no shadow event listener. 108 /// Calling this function allows public process events to be broadcasted to an 109 /// additional listener on top of the default process event listener. 110 /// If the `listener` argument is invalid (SBListener::IsValid() will 111 /// return false), this will clear the shadow listener. 112 void SetShadowListener(SBListener &listener); 113 114 uint32_t GetNumArguments(); 115 116 const char *GetArgumentAtIndex(uint32_t idx); 117 118 void SetArguments(const char **argv, bool append); 119 120 uint32_t GetNumEnvironmentEntries(); 121 122 const char *GetEnvironmentEntryAtIndex(uint32_t idx); 123 124 /// Update this object with the given environment variables. 125 /// 126 /// If append is false, the provided environment will replace the existing 127 /// environment. Otherwise, existing values will be updated of left untouched 128 /// accordingly. 129 /// 130 /// \param [in] envp 131 /// The new environment variables as a list of strings with the following 132 /// format 133 /// name=value 134 /// 135 /// \param [in] append 136 /// Flag that controls whether to replace the existing environment. 137 void SetEnvironmentEntries(const char **envp, bool append); 138 139 /// Update this object with the given environment variables. 140 /// 141 /// If append is false, the provided environment will replace the existing 142 /// environment. Otherwise, existing values will be updated of left untouched 143 /// accordingly. 144 /// 145 /// \param [in] env 146 /// The new environment variables. 147 /// 148 /// \param [in] append 149 /// Flag that controls whether to replace the existing environment. 150 void SetEnvironment(const SBEnvironment &env, bool append); 151 152 /// Return the environment variables of this object. 153 /// 154 /// \return 155 /// An lldb::SBEnvironment object which is a copy of the SBLaunchInfo's 156 /// environment. 157 SBEnvironment GetEnvironment(); 158 159 void Clear(); 160 161 const char *GetWorkingDirectory() const; 162 163 void SetWorkingDirectory(const char *working_dir); 164 165 uint32_t GetLaunchFlags(); 166 167 void SetLaunchFlags(uint32_t flags); 168 169 const char *GetProcessPluginName(); 170 171 void SetProcessPluginName(const char *plugin_name); 172 173 const char *GetShell(); 174 175 void SetShell(const char *path); 176 177 bool GetShellExpandArguments(); 178 179 void SetShellExpandArguments(bool expand); 180 181 uint32_t GetResumeCount(); 182 183 void SetResumeCount(uint32_t c); 184 185 bool AddCloseFileAction(int fd); 186 187 bool AddDuplicateFileAction(int fd, int dup_fd); 188 189 bool AddOpenFileAction(int fd, const char *path, bool read, bool write); 190 191 bool AddSuppressFileAction(int fd, bool read, bool write); 192 193 void SetLaunchEventData(const char *data); 194 195 const char *GetLaunchEventData() const; 196 197 bool GetDetachOnError() const; 198 199 void SetDetachOnError(bool enable); 200 201 const char *GetScriptedProcessClassName() const; 202 203 void SetScriptedProcessClassName(const char *class_name); 204 205 lldb::SBStructuredData GetScriptedProcessDictionary() const; 206 207 void SetScriptedProcessDictionary(lldb::SBStructuredData dict); 208 209 protected: 210 friend class SBPlatform; 211 friend class SBTarget; 212 213 friend class lldb_private::ScriptInterpreter; 214 215 const lldb_private::ProcessLaunchInfo &ref() const; 216 void set_ref(const lldb_private::ProcessLaunchInfo &info); 217 218 std::shared_ptr<lldb_private::SBLaunchInfoImpl> m_opaque_sp; 219 }; 220 221 } // namespace lldb 222 223 #endif // LLDB_API_SBLAUNCHINFO_H 224