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
14namespace lldb_private {
15class SBLaunchInfoImpl;
16class ScriptInterpreter;
17}
18
19namespace lldb {
20
21class SBPlatform;
22class SBTarget;
23
24class LLDB_API SBLaunchInfo {
25public:
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
209protected:
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

source code of lldb/include/lldb/API/SBLaunchInfo.h