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