1 //===-- CommandObjectFrame.cpp ----------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
14 // Other libraries and framework includes
16 #include "CommandObjectFrame.h"
17 #include "lldb/Core/Debugger.h"
18 #include "lldb/Core/Module.h"
19 #include "lldb/Core/StreamFile.h"
20 #include "lldb/Core/StreamString.h"
21 #include "lldb/Core/Timer.h"
22 #include "lldb/Core/Value.h"
23 #include "lldb/Core/ValueObject.h"
24 #include "lldb/Core/ValueObjectVariable.h"
25 #include "lldb/DataFormatters/DataVisualization.h"
26 #include "lldb/DataFormatters/ValueObjectPrinter.h"
27 #include "lldb/Host/Host.h"
28 #include "lldb/Host/StringConvert.h"
29 #include "lldb/Interpreter/Args.h"
30 #include "lldb/Interpreter/CommandInterpreter.h"
31 #include "lldb/Interpreter/CommandReturnObject.h"
32 #include "lldb/Interpreter/Options.h"
33 #include "lldb/Interpreter/OptionGroupFormat.h"
34 #include "lldb/Interpreter/OptionGroupValueObjectDisplay.h"
35 #include "lldb/Interpreter/OptionGroupVariable.h"
36 #include "lldb/Symbol/CompilerType.h"
37 #include "lldb/Symbol/ClangASTContext.h"
38 #include "lldb/Symbol/Function.h"
39 #include "lldb/Symbol/ObjectFile.h"
40 #include "lldb/Symbol/SymbolContext.h"
41 #include "lldb/Symbol/Type.h"
42 #include "lldb/Symbol/Variable.h"
43 #include "lldb/Symbol/VariableList.h"
44 #include "lldb/Target/Process.h"
45 #include "lldb/Target/StackFrame.h"
46 #include "lldb/Target/Thread.h"
47 #include "lldb/Target/Target.h"
50 using namespace lldb_private;
52 #pragma mark CommandObjectFrameInfo
54 //-------------------------------------------------------------------------
55 // CommandObjectFrameInfo
56 //-------------------------------------------------------------------------
58 class CommandObjectFrameInfo : public CommandObjectParsed
61 CommandObjectFrameInfo(CommandInterpreter &interpreter)
62 : CommandObjectParsed(interpreter, "frame info",
63 "List information about the current stack frame in the current thread.", "frame info",
64 eCommandRequiresFrame | eCommandTryTargetAPILock | eCommandProcessMustBeLaunched |
65 eCommandProcessMustBePaused)
69 ~CommandObjectFrameInfo() override = default;
73 DoExecute (Args& command, CommandReturnObject &result) override
75 m_exe_ctx.GetFrameRef().DumpUsingSettingsFormat (&result.GetOutputStream());
76 result.SetStatus (eReturnStatusSuccessFinishResult);
77 return result.Succeeded();
81 #pragma mark CommandObjectFrameSelect
83 //-------------------------------------------------------------------------
84 // CommandObjectFrameSelect
85 //-------------------------------------------------------------------------
87 class CommandObjectFrameSelect : public CommandObjectParsed
90 class CommandOptions : public Options
93 CommandOptions (CommandInterpreter &interpreter) :
96 OptionParsingStarting ();
99 ~CommandOptions() override = default;
102 SetOptionValue (uint32_t option_idx, const char *option_arg) override
105 bool success = false;
106 const int short_option = m_getopt_table[option_idx].val;
107 switch (short_option)
110 relative_frame_offset = StringConvert::ToSInt32 (option_arg, INT32_MIN, 0, &success);
112 error.SetErrorStringWithFormat ("invalid frame offset argument '%s'", option_arg);
116 error.SetErrorStringWithFormat ("invalid short option character '%c'", short_option);
124 OptionParsingStarting () override
126 relative_frame_offset = INT32_MIN;
129 const OptionDefinition*
130 GetDefinitions () override
132 return g_option_table;
135 // Options table: Required for subclasses of Options.
137 static OptionDefinition g_option_table[];
138 int32_t relative_frame_offset;
141 CommandObjectFrameSelect(CommandInterpreter &interpreter)
142 : CommandObjectParsed(
143 interpreter, "frame select",
144 "Select the current stack frame by index from within the current thread (see 'thread backtrace'.)",
145 nullptr, eCommandRequiresThread | eCommandTryTargetAPILock | eCommandProcessMustBeLaunched |
146 eCommandProcessMustBePaused),
147 m_options(interpreter)
149 CommandArgumentEntry arg;
150 CommandArgumentData index_arg;
152 // Define the first (and only) variant of this arg.
153 index_arg.arg_type = eArgTypeFrameIndex;
154 index_arg.arg_repetition = eArgRepeatOptional;
156 // There is only one variant this argument could be; put it into the argument entry.
157 arg.push_back (index_arg);
159 // Push the data for the first argument into the m_arguments vector.
160 m_arguments.push_back (arg);
163 ~CommandObjectFrameSelect() override = default;
166 GetOptions () override
173 DoExecute (Args& command, CommandReturnObject &result) override
175 // No need to check "thread" for validity as eCommandRequiresThread ensures it is valid
176 Thread *thread = m_exe_ctx.GetThreadPtr();
178 uint32_t frame_idx = UINT32_MAX;
179 if (m_options.relative_frame_offset != INT32_MIN)
181 // The one and only argument is a signed relative frame index
182 frame_idx = thread->GetSelectedFrameIndex ();
183 if (frame_idx == UINT32_MAX)
186 if (m_options.relative_frame_offset < 0)
188 if (static_cast<int32_t>(frame_idx) >= -m_options.relative_frame_offset)
189 frame_idx += m_options.relative_frame_offset;
194 //If you are already at the bottom of the stack, then just warn and don't reset the frame.
195 result.AppendError("Already at the bottom of the stack.");
196 result.SetStatus(eReturnStatusFailed);
203 else if (m_options.relative_frame_offset > 0)
205 // I don't want "up 20" where "20" takes you past the top of the stack to produce
206 // an error, but rather to just go to the top. So I have to count the stack here...
207 const uint32_t num_frames = thread->GetStackFrameCount();
208 if (static_cast<int32_t>(num_frames - frame_idx) > m_options.relative_frame_offset)
209 frame_idx += m_options.relative_frame_offset;
212 if (frame_idx == num_frames - 1)
214 //If we are already at the top of the stack, just warn and don't reset the frame.
215 result.AppendError("Already at the top of the stack.");
216 result.SetStatus(eReturnStatusFailed);
220 frame_idx = num_frames - 1;
226 if (command.GetArgumentCount() == 1)
228 const char *frame_idx_cstr = command.GetArgumentAtIndex(0);
229 bool success = false;
230 frame_idx = StringConvert::ToUInt32 (frame_idx_cstr, UINT32_MAX, 0, &success);
233 result.AppendErrorWithFormat("invalid frame index argument '%s'.", frame_idx_cstr);
234 result.SetStatus (eReturnStatusFailed);
238 else if (command.GetArgumentCount() == 0)
240 frame_idx = thread->GetSelectedFrameIndex ();
241 if (frame_idx == UINT32_MAX)
248 result.AppendErrorWithFormat ("too many arguments; expected frame-index, saw '%s'.\n",
249 command.GetArgumentAtIndex(0));
250 m_options.GenerateOptionUsage (result.GetErrorStream(), this);
255 bool success = thread->SetSelectedFrameByIndexNoisily (frame_idx, result.GetOutputStream());
258 m_exe_ctx.SetFrameSP(thread->GetSelectedFrame ());
259 result.SetStatus (eReturnStatusSuccessFinishResult);
263 result.AppendErrorWithFormat ("Frame index (%u) out of range.\n", frame_idx);
264 result.SetStatus (eReturnStatusFailed);
267 return result.Succeeded();
271 CommandOptions m_options;
275 CommandObjectFrameSelect::CommandOptions::g_option_table[] =
277 { LLDB_OPT_SET_1, false, "relative", 'r', OptionParser::eRequiredArgument, nullptr, nullptr, 0, eArgTypeOffset, "A relative frame index offset from the current frame index."},
278 { 0, false, nullptr, 0, 0, nullptr, nullptr, 0, eArgTypeNone, nullptr }
281 #pragma mark CommandObjectFrameVariable
282 //----------------------------------------------------------------------
283 // List images with associated information
284 //----------------------------------------------------------------------
285 class CommandObjectFrameVariable : public CommandObjectParsed
288 CommandObjectFrameVariable(CommandInterpreter &interpreter)
289 : CommandObjectParsed(
290 interpreter, "frame variable", "Show variables for the current stack frame. Defaults to all "
291 "arguments and local variables in scope. Names of argument, "
292 "local, file static and file global variables can be specified. "
293 "Children of aggregate variables can be specified such as "
295 nullptr, eCommandRequiresFrame | eCommandTryTargetAPILock | eCommandProcessMustBeLaunched |
296 eCommandProcessMustBePaused | eCommandRequiresProcess),
297 m_option_group(interpreter),
298 m_option_variable(true), // Include the frame specific options by passing "true"
299 m_option_format(eFormatDefault),
302 CommandArgumentEntry arg;
303 CommandArgumentData var_name_arg;
305 // Define the first (and only) variant of this arg.
306 var_name_arg.arg_type = eArgTypeVarName;
307 var_name_arg.arg_repetition = eArgRepeatStar;
309 // There is only one variant this argument could be; put it into the argument entry.
310 arg.push_back (var_name_arg);
312 // Push the data for the first argument into the m_arguments vector.
313 m_arguments.push_back (arg);
315 m_option_group.Append (&m_option_variable, LLDB_OPT_SET_ALL, LLDB_OPT_SET_1);
316 m_option_group.Append (&m_option_format, OptionGroupFormat::OPTION_GROUP_FORMAT | OptionGroupFormat::OPTION_GROUP_GDB_FMT, LLDB_OPT_SET_1);
317 m_option_group.Append (&m_varobj_options, LLDB_OPT_SET_ALL, LLDB_OPT_SET_1);
318 m_option_group.Finalize();
321 ~CommandObjectFrameVariable() override = default;
324 GetOptions () override
326 return &m_option_group;
330 HandleArgumentCompletion (Args &input,
332 int &cursor_char_position,
333 OptionElementVector &opt_element_vector,
334 int match_start_point,
335 int max_return_elements,
337 StringList &matches) override
339 // Arguments are the standard source file completer.
340 std::string completion_str (input.GetArgumentAtIndex(cursor_index));
341 completion_str.erase (cursor_char_position);
343 CommandCompletions::InvokeCommonCompletionCallbacks(m_interpreter,
344 CommandCompletions::eVariablePathCompletion,
345 completion_str.c_str(),
351 return matches.GetSize();
356 DoExecute (Args& command, CommandReturnObject &result) override
358 // No need to check "frame" for validity as eCommandRequiresFrame ensures it is valid
359 StackFrame *frame = m_exe_ctx.GetFramePtr();
361 Stream &s = result.GetOutputStream();
363 // Be careful about the stack frame, if any summary formatter runs code, it might clear the StackFrameList
364 // for the thread. So hold onto a shared pointer to the frame so it stays alive.
366 VariableList *variable_list = frame->GetVariableList (m_option_variable.show_globals);
369 ValueObjectSP valobj_sp;
371 const char *name_cstr = nullptr;
374 TypeSummaryImplSP summary_format_sp;
375 if (!m_option_variable.summary.IsCurrentValueEmpty())
376 DataVisualization::NamedSummaryFormats::GetSummaryFormat(ConstString(m_option_variable.summary.GetCurrentValue()), summary_format_sp);
377 else if (!m_option_variable.summary_string.IsCurrentValueEmpty())
378 summary_format_sp.reset(new StringSummaryFormat(TypeSummaryImpl::Flags(),m_option_variable.summary_string.GetCurrentValue()));
380 DumpValueObjectOptions options(m_varobj_options.GetAsDumpOptions(eLanguageRuntimeDescriptionDisplayVerbosityFull,eFormatDefault,summary_format_sp));
382 const SymbolContext& sym_ctx = frame->GetSymbolContext(eSymbolContextFunction);
383 if (sym_ctx.function && sym_ctx.function->IsTopLevelFunction())
384 m_option_variable.show_globals = true;
388 const Format format = m_option_format.GetFormat();
389 options.SetFormat(format);
391 if (command.GetArgumentCount() > 0)
393 VariableList regex_var_list;
395 // If we have any args to the variable command, we will make
396 // variable objects from them...
397 for (idx = 0; (name_cstr = command.GetArgumentAtIndex(idx)) != nullptr; ++idx)
399 if (m_option_variable.use_regex)
401 const size_t regex_start_index = regex_var_list.GetSize();
402 RegularExpression regex (name_cstr);
403 if (regex.Compile(name_cstr))
405 size_t num_matches = 0;
406 const size_t num_new_regex_vars = variable_list->AppendVariablesIfUnique(regex,
409 if (num_new_regex_vars > 0)
411 for (size_t regex_idx = regex_start_index, end_index = regex_var_list.GetSize();
412 regex_idx < end_index;
415 var_sp = regex_var_list.GetVariableAtIndex (regex_idx);
418 valobj_sp = frame->GetValueObjectForFrameVariable (var_sp, m_varobj_options.use_dynamic);
421 // if (format != eFormatDefault)
422 // valobj_sp->SetFormat (format);
424 if (m_option_variable.show_decl && var_sp->GetDeclaration ().GetFile())
426 bool show_fullpaths = false;
427 bool show_module = true;
428 if (var_sp->DumpDeclaration(&s, show_fullpaths, show_module))
431 valobj_sp->Dump(result.GetOutputStream(),options);
436 else if (num_matches == 0)
438 result.GetErrorStream().Printf ("error: no variables matched the regular expression '%s'.\n", name_cstr);
443 char regex_error[1024];
444 if (regex.GetErrorAsCString(regex_error, sizeof(regex_error)))
445 result.GetErrorStream().Printf ("error: %s\n", regex_error);
447 result.GetErrorStream().Printf ("error: unknown regex error when compiling '%s'\n", name_cstr);
450 else // No regex, either exact variable names or variable expressions.
453 uint32_t expr_path_options = StackFrame::eExpressionPathOptionCheckPtrVsMember |
454 StackFrame::eExpressionPathOptionsAllowDirectIVarAccess |
455 StackFrame::eExpressionPathOptionsInspectAnonymousUnions;
456 lldb::VariableSP var_sp;
457 valobj_sp = frame->GetValueForVariableExpressionPath (name_cstr,
458 m_varobj_options.use_dynamic,
464 // if (format != eFormatDefault)
465 // valobj_sp->SetFormat (format);
466 if (m_option_variable.show_decl && var_sp && var_sp->GetDeclaration ().GetFile())
468 var_sp->GetDeclaration ().DumpStopContext (&s, false);
472 options.SetFormat(format);
473 options.SetVariableFormatDisplayLanguage(valobj_sp->GetPreferredDisplayLanguage());
475 Stream &output_stream = result.GetOutputStream();
476 options.SetRootValueObjectName(valobj_sp->GetParent() ? name_cstr : nullptr);
477 valobj_sp->Dump(output_stream,options);
481 const char *error_cstr = error.AsCString(nullptr);
483 result.GetErrorStream().Printf("error: %s\n", error_cstr);
485 result.GetErrorStream().Printf(
486 "error: unable to find any variable expression path that matches '%s'.\n",
492 else // No command arg specified. Use variable_list, instead.
494 const size_t num_variables = variable_list->GetSize();
495 if (num_variables > 0)
497 for (size_t i=0; i<num_variables; i++)
499 var_sp = variable_list->GetVariableAtIndex(i);
500 bool dump_variable = true;
501 std::string scope_string;
502 switch (var_sp->GetScope())
504 case eValueTypeVariableGlobal:
505 // Always dump globals since we only fetched them if
506 // m_option_variable.show_scope was true
507 if (dump_variable && m_option_variable.show_scope)
508 scope_string = "GLOBAL: ";
511 case eValueTypeVariableStatic:
512 // Always dump globals since we only fetched them if
513 // m_option_variable.show_scope was true, or this is
514 // a static variable from a block in the current scope
515 if (dump_variable && m_option_variable.show_scope)
516 scope_string = "STATIC: ";
519 case eValueTypeVariableArgument:
520 dump_variable = m_option_variable.show_args;
521 if (dump_variable && m_option_variable.show_scope)
522 scope_string = " ARG: ";
525 case eValueTypeVariableLocal:
526 dump_variable = m_option_variable.show_locals;
527 if (dump_variable && m_option_variable.show_scope)
528 scope_string = " LOCAL: ";
531 case eValueTypeVariableThreadLocal:
532 if (dump_variable && m_option_variable.show_scope)
533 scope_string = "THREAD: ";
541 // Use the variable object code to make sure we are
542 // using the same APIs as the public API will be
544 valobj_sp = frame->GetValueObjectForFrameVariable (var_sp,
545 m_varobj_options.use_dynamic);
548 // if (format != eFormatDefault)
549 // valobj_sp->SetFormat (format);
551 // When dumping all variables, don't print any variables
552 // that are not in scope to avoid extra unneeded output
553 if (valobj_sp->IsInScope ())
555 if (!valobj_sp->GetTargetSP()->GetDisplayRuntimeSupportValues() &&
556 valobj_sp->IsRuntimeSupportValue())
559 if (!scope_string.empty())
560 s.PutCString(scope_string.c_str());
562 if (m_option_variable.show_decl && var_sp->GetDeclaration ().GetFile())
564 var_sp->GetDeclaration ().DumpStopContext (&s, false);
568 options.SetFormat(format);
569 options.SetVariableFormatDisplayLanguage(valobj_sp->GetPreferredDisplayLanguage());
570 options.SetRootValueObjectName(name_cstr);
571 valobj_sp->Dump(result.GetOutputStream(),options);
578 result.SetStatus (eReturnStatusSuccessFinishResult);
581 if (m_interpreter.TruncationWarningNecessary())
583 result.GetOutputStream().Printf(m_interpreter.TruncationWarningText(),
585 m_interpreter.TruncationWarningGiven();
588 return result.Succeeded();
592 OptionGroupOptions m_option_group;
593 OptionGroupVariable m_option_variable;
594 OptionGroupFormat m_option_format;
595 OptionGroupValueObjectDisplay m_varobj_options;
598 #pragma mark CommandObjectMultiwordFrame
600 //-------------------------------------------------------------------------
601 // CommandObjectMultiwordFrame
602 //-------------------------------------------------------------------------
604 CommandObjectMultiwordFrame::CommandObjectMultiwordFrame(CommandInterpreter &interpreter)
605 : CommandObjectMultiword(interpreter, "frame",
606 "Commands for selecting and examing the current thread's stack frames.",
607 "frame <subcommand> [<subcommand-options>]")
609 LoadSubCommand ("info", CommandObjectSP (new CommandObjectFrameInfo (interpreter)));
610 LoadSubCommand ("select", CommandObjectSP (new CommandObjectFrameSelect (interpreter)));
611 LoadSubCommand ("variable", CommandObjectSP (new CommandObjectFrameVariable (interpreter)));
614 CommandObjectMultiwordFrame::~CommandObjectMultiwordFrame() = default;