SBTarget.h revision 03c8ee5aeafcd6c43f10002a4f8096af01780f86 
1//===-- SBTarget.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 LLDB_SBTarget_h_
11#define LLDB_SBTarget_h_
12
13#include "lldb/API/SBDefines.h"
14#include "lldb/API/SBAddress.h"
15#include "lldb/API/SBBroadcaster.h"
16#include "lldb/API/SBFileSpec.h"
17#include "lldb/API/SBType.h"
18
19namespace lldb {
20
21class SBBreakpoint;
22
23class SBTarget
24{
25public:
26    //------------------------------------------------------------------
27    // Broadcaster bits.
28    //------------------------------------------------------------------
29    enum
30    {
31        eBroadcastBitBreakpointChanged  = (1 << 0),
32        eBroadcastBitModulesLoaded      = (1 << 1),
33        eBroadcastBitModulesUnloaded    = (1 << 2)
34    };
35
36    //------------------------------------------------------------------
37    // Constructors
38    //------------------------------------------------------------------
39    SBTarget ();
40
41    SBTarget (const lldb::SBTarget& rhs);
42
43#ifndef SWIG
44    const lldb::SBTarget&
45    operator = (const lldb::SBTarget& rhs);
46#endif
47
48    //------------------------------------------------------------------
49    // Destructor
50    //------------------------------------------------------------------
51    ~SBTarget();
52
53    bool
54    IsValid() const;
55
56    lldb::SBProcess
57    GetProcess ();
58
59    //------------------------------------------------------------------
60    /// Launch a new process.
61    ///
62    /// Launch a new process by spawning a new process using the
63    /// target object's executable module's file as the file to launch.
64    /// Arguments are given in \a argv, and the environment variables
65    /// are in \a envp. Standard input and output files can be
66    /// optionally re-directed to \a stdin_path, \a stdout_path, and
67    /// \a stderr_path.
68    ///
69    /// @param[in] listener
70    ///     An optional listener that will receive all process events.
71    ///     If \a listener is valid then \a listener will listen to all
72    ///     process events. If not valid, then this target's debugger
73    ///     (SBTarget::GetDebugger()) will listen to all process events.
74    ///
75    /// @param[in] argv
76    ///     The argument array.
77    ///
78    /// @param[in] envp
79    ///     The environment array.
80    ///
81    /// @param[in] launch_flags
82    ///     Flags to modify the launch (@see lldb::LaunchFlags)
83    ///
84    /// @param[in] stdin_path
85    ///     The path to use when re-directing the STDIN of the new
86    ///     process. If all stdXX_path arguments are NULL, a pseudo
87    ///     terminal will be used.
88    ///
89    /// @param[in] stdout_path
90    ///     The path to use when re-directing the STDOUT of the new
91    ///     process. If all stdXX_path arguments are NULL, a pseudo
92    ///     terminal will be used.
93    ///
94    /// @param[in] stderr_path
95    ///     The path to use when re-directing the STDERR of the new
96    ///     process. If all stdXX_path arguments are NULL, a pseudo
97    ///     terminal will be used.
98    ///
99    /// @param[in] working_directory
100    ///     The working directory to have the child process run in
101    ///
102    /// @param[in] launch_flags
103    ///     Some launch options specified by logical OR'ing
104    ///     lldb::LaunchFlags enumeration values together.
105    ///
106    /// @param[in] stop_at_endtry
107    ///     If false do not stop the inferior at the entry point.
108    ///
109    /// @param[out]
110    ///     An error object. Contains the reason if there is some failure.
111    ///
112    /// @return
113    ///      A process object for the newly created process.
114    //------------------------------------------------------------------
115    lldb::SBProcess
116    Launch (SBListener &listener,
117            char const **argv,
118            char const **envp,
119            const char *stdin_path,
120            const char *stdout_path,
121            const char *stderr_path,
122            const char *working_directory,
123            uint32_t launch_flags,   // See LaunchFlags
124            bool stop_at_entry,
125            lldb::SBError& error);
126
127
128    //------------------------------------------------------------------
129    /// Launch a new process with sensible defaults.
130    ///
131    /// @param[in] argv
132    ///     The argument array.
133    ///
134    /// @param[in] envp
135    ///     The environment array.
136    ///
137    /// @param[in] working_directory
138    ///     The working directory to have the child process run in
139    ///
140    /// Default: listener
141    ///     Set to the target's debugger (SBTarget::GetDebugger())
142    ///
143    /// Default: launch_flags
144    ///     Empty launch flags
145    ///
146    /// Default: stdin_path
147    /// Default: stdout_path
148    /// Default: stderr_path
149    ///     A pseudo terminal will be used.
150    ///
151    /// @return
152    ///      A process object for the newly created process.
153    //------------------------------------------------------------------
154    lldb::SBProcess
155    LaunchSimple (const char **argv,
156                  const char **envp,
157                  const char *working_directory);
158
159    //------------------------------------------------------------------
160    /// Attach to process with pid.
161    ///
162    /// @param[in] listener
163    ///     An optional listener that will receive all process events.
164    ///     If \a listener is valid then \a listener will listen to all
165    ///     process events. If not valid, then this target's debugger
166    ///     (SBTarget::GetDebugger()) will listen to all process events.
167    ///
168    /// @param[in] pid
169    ///     The process ID to attach to.
170    ///
171    /// @param[out]
172    ///     An error explaining what went wrong if attach fails.
173    ///
174    /// @return
175    ///      A process object for the attached process.
176    //------------------------------------------------------------------
177    lldb::SBProcess
178    AttachToProcessWithID (SBListener &listener,
179                           lldb::pid_t pid,
180                           lldb::SBError& error);
181
182    //------------------------------------------------------------------
183    /// Attach to process with name.
184    ///
185    /// @param[in] listener
186    ///     An optional listener that will receive all process events.
187    ///     If \a listener is valid then \a listener will listen to all
188    ///     process events. If not valid, then this target's debugger
189    ///     (SBTarget::GetDebugger()) will listen to all process events.
190    ///
191    /// @param[in] name
192    ///     Basename of process to attach to.
193    ///
194    /// @param[in] wait_for
195    ///     If true wait for a new instance of 'name' to be launched.
196    ///
197    /// @param[out]
198    ///     An error explaining what went wrong if attach fails.
199    ///
200    /// @return
201    ///      A process object for the attached process.
202    //------------------------------------------------------------------
203    lldb::SBProcess
204    AttachToProcessWithName (SBListener &listener,
205                             const char *name,
206                             bool wait_for,
207                             lldb::SBError& error);
208
209    //------------------------------------------------------------------
210    /// Connect to a remote debug server with url.
211    ///
212    /// @param[in] listener
213    ///     An optional listener that will receive all process events.
214    ///     If \a listener is valid then \a listener will listen to all
215    ///     process events. If not valid, then this target's debugger
216    ///     (SBTarget::GetDebugger()) will listen to all process events.
217    ///
218    /// @param[in] url
219    ///     The url to connect to, e.g., 'connect://localhost:12345'.
220    ///
221    /// @param[in] plugin_name
222    ///     The plugin name to be used; can be NULL.
223    ///
224    /// @param[out]
225    ///     An error explaining what went wrong if the connect fails.
226    ///
227    /// @return
228    ///      A process object for the connected process.
229    //------------------------------------------------------------------
230    lldb::SBProcess
231    ConnectRemote (SBListener &listener,
232                   const char *url,
233                   const char *plugin_name,
234                   SBError& error);
235
236    lldb::SBFileSpec
237    GetExecutable ();
238
239    uint32_t
240    GetNumModules () const;
241
242    lldb::SBModule
243    GetModuleAtIndex (uint32_t idx);
244
245    lldb::SBDebugger
246    GetDebugger() const;
247
248    lldb::SBModule
249    FindModule (const lldb::SBFileSpec &file_spec);
250
251    //------------------------------------------------------------------
252    /// Find functions by name.
253    ///
254    /// @param[in] name
255    ///     The name of the function we are looking for.
256    ///
257    /// @param[in] name_type_mask
258    ///     A logical OR of one or more FunctionNameType enum bits that
259    ///     indicate what kind of names should be used when doing the
260    ///     lookup. Bits include fully qualified names, base names,
261    ///     C++ methods, or ObjC selectors.
262    ///     See FunctionNameType for more details.
263    ///
264    /// @param[in] append
265    ///     If true, any matches will be appended to \a sc_list, else
266    ///     matches replace the contents of \a sc_list.
267    ///
268    /// @param[out] sc_list
269    ///     A symbol context list that gets filled in with all of the
270    ///     matches.
271    ///
272    /// @return
273    ///     The number of matches added to \a sc_list.
274    //------------------------------------------------------------------
275    uint32_t
276    FindFunctions (const char *name,
277                   uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits
278                   bool append,
279                   lldb::SBSymbolContextList& sc_list);
280
281    //------------------------------------------------------------------
282    /// Find global and static variables by name.
283    ///
284    /// @param[in] name
285    ///     The name of the global or static variable we are looking
286    ///     for.
287    ///
288    /// @param[in] max_matches
289    ///     Allow the number of matches to be limited to \a max_matches.
290    ///
291    /// @return
292    ///     A list of matched variables in an SBValueList.
293    //------------------------------------------------------------------
294    lldb::SBValueList
295    FindGlobalVariables (const char *name,
296                         uint32_t max_matches);
297
298    void
299    Clear ();
300
301    lldb::SBAddress
302    ResolveLoadAddress (lldb::addr_t vm_addr);
303
304    SBSymbolContext
305    ResolveSymbolContextForAddress (const SBAddress& addr,
306                                    uint32_t resolve_scope);
307
308    lldb::SBBreakpoint
309    BreakpointCreateByLocation (const char *file, uint32_t line);
310
311    lldb::SBBreakpoint
312    BreakpointCreateByLocation (const lldb::SBFileSpec &file_spec, uint32_t line);
313
314    lldb::SBBreakpoint
315    BreakpointCreateByName (const char *symbol_name, const char *module_name = NULL);
316
317    lldb::SBBreakpoint
318    BreakpointCreateByRegex (const char *symbol_name_regex, const char *module_name = NULL);
319
320    lldb::SBBreakpoint
321    BreakpointCreateBySourceRegex (const char *source_regex, const lldb::SBFileSpec &source_file, const char *module_name = NULL);
322
323    lldb::SBBreakpoint
324    BreakpointCreateByAddress (addr_t address);
325
326    uint32_t
327    GetNumBreakpoints () const;
328
329    lldb::SBBreakpoint
330    GetBreakpointAtIndex (uint32_t idx) const;
331
332    bool
333    BreakpointDelete (break_id_t break_id);
334
335    lldb::SBBreakpoint
336    FindBreakpointByID (break_id_t break_id);
337
338    bool
339    EnableAllBreakpoints ();
340
341    bool
342    DisableAllBreakpoints ();
343
344    bool
345    DeleteAllBreakpoints ();
346
347    lldb::SBBroadcaster
348    GetBroadcaster () const;
349
350    lldb::SBType
351    FindFirstType (const char* type);
352
353    lldb::SBTypeList
354    FindTypes (const char* type);
355
356    SBSourceManager
357    GetSourceManager();
358
359#ifndef SWIG
360    bool
361    operator == (const lldb::SBTarget &rhs) const;
362
363    bool
364    operator != (const lldb::SBTarget &rhs) const;
365
366#endif
367
368#ifndef SWIG
369    bool
370    GetDescription (lldb::SBStream &description, lldb::DescriptionLevel description_level);
371#endif
372
373    bool
374    GetDescription (lldb::SBStream &description, lldb::DescriptionLevel description_level) const;
375
376protected:
377    friend class SBAddress;
378    friend class SBDebugger;
379    friend class SBFunction;
380    friend class SBProcess;
381    friend class SBSymbol;
382    friend class SBModule;
383    friend class SBValue;
384    friend class SBSourceManager_impl;
385
386    //------------------------------------------------------------------
387    // Constructors are private, use static Target::Create function to
388    // create an instance of this class.
389    //------------------------------------------------------------------
390
391    SBTarget (const lldb::TargetSP& target_sp);
392
393    void
394    reset (const lldb::TargetSP& target_sp);
395
396    lldb_private::Target *
397    operator ->() const;
398
399    lldb_private::Target *
400    get() const;
401
402private:
403    //------------------------------------------------------------------
404    // For Target only
405    //------------------------------------------------------------------
406
407    lldb::TargetSP m_opaque_sp;
408};
409
410} // namespace lldb
411
412#endif  // LLDB_SBTarget_h_
413