1 //===-- CommandObjectWatchpointCommand.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 //===----------------------------------------------------------------------===//
10 #include "lldb/lldb-python.h"
16 #include "CommandObjectWatchpointCommand.h"
17 #include "CommandObjectWatchpoint.h"
19 #include "lldb/Core/IOHandler.h"
20 #include "lldb/Interpreter/CommandInterpreter.h"
21 #include "lldb/Interpreter/CommandReturnObject.h"
22 #include "lldb/Target/Target.h"
23 #include "lldb/Target/Thread.h"
24 #include "lldb/Breakpoint/Watchpoint.h"
25 #include "lldb/Breakpoint/StoppointCallbackContext.h"
26 #include "lldb/Core/State.h"
31 using namespace lldb_private;
33 //-------------------------------------------------------------------------
34 // CommandObjectWatchpointCommandAdd
35 //-------------------------------------------------------------------------
38 class CommandObjectWatchpointCommandAdd :
39 public CommandObjectParsed,
40 public IOHandlerDelegateMultiline
44 CommandObjectWatchpointCommandAdd (CommandInterpreter &interpreter) :
45 CommandObjectParsed (interpreter,
47 "Add a set of commands to a watchpoint, to be executed whenever the watchpoint is hit.",
49 IOHandlerDelegateMultiline("DONE", IOHandlerDelegate::Completion::LLDBCommand),
50 m_options (interpreter)
53 "\nGeneral information about entering watchpoint commands \n\
54 ------------------------------------------------------ \n\
56 This command will cause you to be prompted to enter the command or set \n\
57 of commands you wish to be executed when the specified watchpoint is \n\
58 hit. You will be told to enter your command(s), and will see a '> ' \n\
59 prompt. Because you can enter one or many commands to be executed when \n\
60 a watchpoint is hit, you will continue to be prompted after each \n\
61 new-line that you enter, until you enter the word 'DONE', which will \n\
62 cause the commands you have entered to be stored with the watchpoint \n\
63 and executed when the watchpoint is hit. \n\
65 Syntax checking is not necessarily done when watchpoint commands are \n\
66 entered. An improperly written watchpoint command will attempt to get \n\
67 executed when the watchpoint gets hit, and usually silently fail. If \n\
68 your watchpoint command does not appear to be getting executed, go \n\
69 back and check your syntax. \n\
72 Special information about PYTHON watchpoint commands \n\
73 ---------------------------------------------------- \n\
75 You may enter either one line of Python or multiple lines of Python \n\
76 (including defining whole functions, if desired). If you enter a \n\
77 single line of Python, that will be passed to the Python interpreter \n\
78 'as is' when the watchpoint gets hit. If you enter function \n\
79 definitions, they will be passed to the Python interpreter as soon as \n\
80 you finish entering the watchpoint command, and they can be called \n\
81 later (don't forget to add calls to them, if you want them called when \n\
82 the watchpoint is hit). If you enter multiple lines of Python that \n\
83 are not function definitions, they will be collected into a new, \n\
84 automatically generated Python function, and a call to the newly \n\
85 generated function will be attached to the watchpoint. \n\
87 This auto-generated function is passed in two arguments: \n\
89 frame: an SBFrame object representing the frame which hit the watchpoint. \n\
90 From the frame you can get back to the thread and process. \n\
91 wp: the watchpoint that was hit. \n\
93 Important Note: Because loose Python code gets collected into functions, \n\
94 if you want to access global variables in the 'loose' code, you need to \n\
95 specify that they are global, using the 'global' keyword. Be sure to \n\
96 use correct Python syntax, including indentation, when entering Python \n\
97 watchpoint commands. \n\
99 As a third option, you can pass the name of an already existing Python function \n\
100 and that function will be attached to the watchpoint. It will get passed the \n\
101 frame and wp_loc arguments mentioned above. \n\
103 Example Python one-line watchpoint command: \n\
105 (lldb) watchpoint command add -s python 1 \n\
106 Enter your Python command(s). Type 'DONE' to end. \n\
107 > print \"Hit this watchpoint!\" \n\
110 As a convenience, this also works for a short Python one-liner: \n\
111 (lldb) watchpoint command add -s python 1 -o \"import time; print time.asctime()\" \n\
113 Launching '.../a.out' (x86_64) \n\
114 (lldb) Fri Sep 10 12:17:45 2010 \n\
115 Process 21778 Stopped \n\
116 * thread #1: tid = 0x2e03, 0x0000000100000de8 a.out`c + 7 at main.c:39, stop reason = watchpoint 1.1, queue = com.apple.main-thread \n\
120 39 -> return val + 3;\n\
123 42 int main (int argc, char const *argv[])\n\
126 Example multiple line Python watchpoint command, using function definition: \n\
128 (lldb) watchpoint command add -s python 1 \n\
129 Enter your Python command(s). Type 'DONE' to end. \n\
130 > def watchpoint_output (wp_no): \n\
131 > out_string = \"Hit watchpoint number \" + repr (wp_no) \n\
132 > print out_string \n\
134 > watchpoint_output (1) \n\
138 Example multiple line Python watchpoint command, using 'loose' Python: \n\
140 (lldb) watchpoint command add -s p 1 \n\
141 Enter your Python command(s). Type 'DONE' to end. \n\
142 > global wp_count \n\
143 > wp_count = wp_count + 1 \n\
144 > print \"Hit this watchpoint \" + repr(wp_count) + \" times!\" \n\
147 In this case, since there is a reference to a global variable, \n\
148 'wp_count', you will also need to make sure 'wp_count' exists and is \n\
158 Final Note: If you get a warning that no watchpoint command was generated, \n\
159 but you did not get any syntax errors, you probably forgot to add a call \n\
160 to your functions. \n\
162 Special information about debugger command watchpoint commands \n\
163 -------------------------------------------------------------- \n\
165 You may enter any debugger command, exactly as you would at the \n\
166 debugger prompt. You may enter as many debugger commands as you like, \n\
167 but do NOT enter more than one command per line. \n" );
169 CommandArgumentEntry arg;
170 CommandArgumentData wp_id_arg;
172 // Define the first (and only) variant of this arg.
173 wp_id_arg.arg_type = eArgTypeWatchpointID;
174 wp_id_arg.arg_repetition = eArgRepeatPlain;
176 // There is only one variant this argument could be; put it into the argument entry.
177 arg.push_back (wp_id_arg);
179 // Push the data for the first argument into the m_arguments vector.
180 m_arguments.push_back (arg);
184 ~CommandObjectWatchpointCommandAdd () {}
193 IOHandlerActivated (IOHandler &io_handler)
195 StreamFileSP output_sp(io_handler.GetOutputStreamFile());
198 output_sp->PutCString("Enter your debugger command(s). Type 'DONE' to end.\n");
205 IOHandlerInputComplete (IOHandler &io_handler, std::string &line)
207 io_handler.SetIsDone(true);
209 // The WatchpointOptions object is owned by the watchpoint or watchpoint location
210 WatchpointOptions *wp_options = (WatchpointOptions *) io_handler.GetUserData();
213 std::unique_ptr<WatchpointOptions::CommandData> data_ap(new WatchpointOptions::CommandData());
216 data_ap->user_source.SplitIntoLines(line);
217 BatonSP baton_sp (new WatchpointOptions::CommandBaton (data_ap.release()));
218 wp_options->SetCallback (WatchpointOptionsCallbackFunction, baton_sp);
224 CollectDataForWatchpointCommandCallback (WatchpointOptions *wp_options,
225 CommandReturnObject &result)
227 m_interpreter.GetLLDBCommandsFromIOHandler ("> ", // Prompt
228 *this, // IOHandlerDelegate
229 true, // Run IOHandler in async mode
230 wp_options); // Baton for the "io_handler" that will be passed back into our IOHandlerDelegate functions
233 /// Set a one-liner as the callback for the watchpoint.
235 SetWatchpointCommandCallback (WatchpointOptions *wp_options,
236 const char *oneliner)
238 std::unique_ptr<WatchpointOptions::CommandData> data_ap(new WatchpointOptions::CommandData());
240 // It's necessary to set both user_source and script_source to the oneliner.
241 // The former is used to generate callback description (as in watchpoint command list)
242 // while the latter is used for Python to interpret during the actual callback.
243 data_ap->user_source.AppendString (oneliner);
244 data_ap->script_source.assign (oneliner);
245 data_ap->stop_on_error = m_options.m_stop_on_error;
247 BatonSP baton_sp (new WatchpointOptions::CommandBaton (data_ap.release()));
248 wp_options->SetCallback (WatchpointOptionsCallbackFunction, baton_sp);
254 WatchpointOptionsCallbackFunction (void *baton,
255 StoppointCallbackContext *context,
256 lldb::user_id_t watch_id)
258 bool ret_value = true;
263 WatchpointOptions::CommandData *data = (WatchpointOptions::CommandData *) baton;
264 StringList &commands = data->user_source;
266 if (commands.GetSize() > 0)
268 ExecutionContext exe_ctx (context->exe_ctx_ref);
269 Target *target = exe_ctx.GetTargetPtr();
272 CommandReturnObject result;
273 Debugger &debugger = target->GetDebugger();
274 // Rig up the results secondary output stream to the debugger's, so the output will come out synchronously
275 // if the debugger is set up that way.
277 StreamSP output_stream (debugger.GetAsyncOutputStream());
278 StreamSP error_stream (debugger.GetAsyncErrorStream());
279 result.SetImmediateOutputStream (output_stream);
280 result.SetImmediateErrorStream (error_stream);
282 bool stop_on_continue = true;
283 bool echo_commands = false;
284 bool print_results = true;
286 debugger.GetCommandInterpreter().HandleCommands (commands,
294 result.GetImmediateOutputStream()->Flush();
295 result.GetImmediateErrorStream()->Flush();
301 class CommandOptions : public Options
305 CommandOptions (CommandInterpreter &interpreter) :
306 Options (interpreter),
307 m_use_commands (false),
308 m_use_script_language (false),
309 m_script_language (eScriptLanguageNone),
310 m_use_one_liner (false),
317 ~CommandOptions () {}
320 SetOptionValue (uint32_t option_idx, const char *option_arg)
323 const int short_option = m_getopt_table[option_idx].val;
325 switch (short_option)
328 m_use_one_liner = true;
329 m_one_liner = option_arg;
333 m_script_language = (lldb::ScriptLanguage) Args::StringToOptionEnum (option_arg,
334 g_option_table[option_idx].enum_values,
338 if (m_script_language == eScriptLanguagePython || m_script_language == eScriptLanguageDefault)
340 m_use_script_language = true;
344 m_use_script_language = false;
350 bool success = false;
351 m_stop_on_error = Args::StringToBoolean(option_arg, false, &success);
353 error.SetErrorStringWithFormat("invalid value for stop-on-error: \"%s\"", option_arg);
359 m_use_one_liner = false;
360 m_use_script_language = true;
361 m_function_name.assign(option_arg);
371 OptionParsingStarting ()
373 m_use_commands = true;
374 m_use_script_language = false;
375 m_script_language = eScriptLanguageNone;
377 m_use_one_liner = false;
378 m_stop_on_error = true;
380 m_function_name.clear();
383 const OptionDefinition*
386 return g_option_table;
389 // Options table: Required for subclasses of Options.
391 static OptionDefinition g_option_table[];
393 // Instance variables to hold the values for command options.
396 bool m_use_script_language;
397 lldb::ScriptLanguage m_script_language;
399 // Instance variables to hold the values for one_liner options.
400 bool m_use_one_liner;
401 std::string m_one_liner;
402 bool m_stop_on_error;
403 std::string m_function_name;
408 DoExecute (Args& command, CommandReturnObject &result)
410 Target *target = m_interpreter.GetDebugger().GetSelectedTarget().get();
414 result.AppendError ("There is not a current executable; there are no watchpoints to which to add commands");
415 result.SetStatus (eReturnStatusFailed);
419 const WatchpointList &watchpoints = target->GetWatchpointList();
420 size_t num_watchpoints = watchpoints.GetSize();
422 if (num_watchpoints == 0)
424 result.AppendError ("No watchpoints exist to have commands added");
425 result.SetStatus (eReturnStatusFailed);
429 if (m_options.m_use_script_language == false && m_options.m_function_name.size())
431 result.AppendError ("need to enable scripting to have a function run as a watchpoint command");
432 result.SetStatus (eReturnStatusFailed);
436 std::vector<uint32_t> valid_wp_ids;
437 if (!CommandObjectMultiwordWatchpoint::VerifyWatchpointIDs(target, command, valid_wp_ids))
439 result.AppendError("Invalid watchpoints specification.");
440 result.SetStatus(eReturnStatusFailed);
444 result.SetStatus(eReturnStatusSuccessFinishNoResult);
445 const size_t count = valid_wp_ids.size();
446 for (size_t i = 0; i < count; ++i)
448 uint32_t cur_wp_id = valid_wp_ids.at (i);
449 if (cur_wp_id != LLDB_INVALID_WATCH_ID)
451 Watchpoint *wp = target->GetWatchpointList().FindByID (cur_wp_id).get();
452 // Sanity check wp first.
453 if (wp == NULL) continue;
455 WatchpointOptions *wp_options = wp->GetOptions();
456 // Skip this watchpoint if wp_options is not good.
457 if (wp_options == NULL) continue;
459 // If we are using script language, get the script interpreter
460 // in order to set or collect command callback. Otherwise, call
461 // the methods associated with this object.
462 if (m_options.m_use_script_language)
464 // Special handling for one-liner specified inline.
465 if (m_options.m_use_one_liner)
467 m_interpreter.GetScriptInterpreter()->SetWatchpointCommandCallback (wp_options,
468 m_options.m_one_liner.c_str());
470 // Special handling for using a Python function by name
471 // instead of extending the watchpoint callback data structures, we just automatize
472 // what the user would do manually: make their watchpoint command be a function call
473 else if (m_options.m_function_name.size())
475 std::string oneliner(m_options.m_function_name);
476 oneliner += "(frame, wp, internal_dict)";
477 m_interpreter.GetScriptInterpreter()->SetWatchpointCommandCallback (wp_options,
482 m_interpreter.GetScriptInterpreter()->CollectDataForWatchpointCommandCallback (wp_options,
488 // Special handling for one-liner specified inline.
489 if (m_options.m_use_one_liner)
490 SetWatchpointCommandCallback (wp_options,
491 m_options.m_one_liner.c_str());
493 CollectDataForWatchpointCommandCallback (wp_options,
499 return result.Succeeded();
503 CommandOptions m_options;
507 // FIXME: "script-type" needs to have its contents determined dynamically, so somebody can add a new scripting
508 // language to lldb and have it pickable here without having to change this enumeration by hand and rebuild lldb proper.
510 static OptionEnumValueElement
511 g_script_option_enumeration[4] =
513 { eScriptLanguageNone, "command", "Commands are in the lldb command interpreter language"},
514 { eScriptLanguagePython, "python", "Commands are in the Python language."},
515 { eSortOrderByName, "default-script", "Commands are in the default scripting language."},
520 CommandObjectWatchpointCommandAdd::CommandOptions::g_option_table[] =
522 { LLDB_OPT_SET_1, false, "one-liner", 'o', OptionParser::eRequiredArgument, NULL, 0, eArgTypeOneLiner,
523 "Specify a one-line watchpoint command inline. Be sure to surround it with quotes." },
525 { LLDB_OPT_SET_ALL, false, "stop-on-error", 'e', OptionParser::eRequiredArgument, NULL, 0, eArgTypeBoolean,
526 "Specify whether watchpoint command execution should terminate on error." },
528 { LLDB_OPT_SET_ALL, false, "script-type", 's', OptionParser::eRequiredArgument, g_script_option_enumeration, 0, eArgTypeNone,
529 "Specify the language for the commands - if none is specified, the lldb command interpreter will be used."},
531 { LLDB_OPT_SET_2, false, "python-function", 'F', OptionParser::eRequiredArgument, NULL, 0, eArgTypePythonFunction,
532 "Give the name of a Python function to run as command for this watchpoint. Be sure to give a module name if appropriate."},
534 { 0, false, NULL, 0, 0, NULL, 0, eArgTypeNone, NULL }
537 //-------------------------------------------------------------------------
538 // CommandObjectWatchpointCommandDelete
539 //-------------------------------------------------------------------------
541 class CommandObjectWatchpointCommandDelete : public CommandObjectParsed
544 CommandObjectWatchpointCommandDelete (CommandInterpreter &interpreter) :
545 CommandObjectParsed (interpreter,
547 "Delete the set of commands from a watchpoint.",
550 CommandArgumentEntry arg;
551 CommandArgumentData wp_id_arg;
553 // Define the first (and only) variant of this arg.
554 wp_id_arg.arg_type = eArgTypeWatchpointID;
555 wp_id_arg.arg_repetition = eArgRepeatPlain;
557 // There is only one variant this argument could be; put it into the argument entry.
558 arg.push_back (wp_id_arg);
560 // Push the data for the first argument into the m_arguments vector.
561 m_arguments.push_back (arg);
566 ~CommandObjectWatchpointCommandDelete () {}
570 DoExecute (Args& command, CommandReturnObject &result)
572 Target *target = m_interpreter.GetDebugger().GetSelectedTarget().get();
576 result.AppendError ("There is not a current executable; there are no watchpoints from which to delete commands");
577 result.SetStatus (eReturnStatusFailed);
581 const WatchpointList &watchpoints = target->GetWatchpointList();
582 size_t num_watchpoints = watchpoints.GetSize();
584 if (num_watchpoints == 0)
586 result.AppendError ("No watchpoints exist to have commands deleted");
587 result.SetStatus (eReturnStatusFailed);
591 if (command.GetArgumentCount() == 0)
593 result.AppendError ("No watchpoint specified from which to delete the commands");
594 result.SetStatus (eReturnStatusFailed);
598 std::vector<uint32_t> valid_wp_ids;
599 if (!CommandObjectMultiwordWatchpoint::VerifyWatchpointIDs(target, command, valid_wp_ids))
601 result.AppendError("Invalid watchpoints specification.");
602 result.SetStatus(eReturnStatusFailed);
606 result.SetStatus(eReturnStatusSuccessFinishNoResult);
607 const size_t count = valid_wp_ids.size();
608 for (size_t i = 0; i < count; ++i)
610 uint32_t cur_wp_id = valid_wp_ids.at (i);
611 if (cur_wp_id != LLDB_INVALID_WATCH_ID)
613 Watchpoint *wp = target->GetWatchpointList().FindByID (cur_wp_id).get();
619 result.AppendErrorWithFormat("Invalid watchpoint ID: %u.\n",
621 result.SetStatus (eReturnStatusFailed);
625 return result.Succeeded();
629 //-------------------------------------------------------------------------
630 // CommandObjectWatchpointCommandList
631 //-------------------------------------------------------------------------
633 class CommandObjectWatchpointCommandList : public CommandObjectParsed
636 CommandObjectWatchpointCommandList (CommandInterpreter &interpreter) :
637 CommandObjectParsed (interpreter,
639 "List the script or set of commands to be executed when the watchpoint is hit.",
642 CommandArgumentEntry arg;
643 CommandArgumentData wp_id_arg;
645 // Define the first (and only) variant of this arg.
646 wp_id_arg.arg_type = eArgTypeWatchpointID;
647 wp_id_arg.arg_repetition = eArgRepeatPlain;
649 // There is only one variant this argument could be; put it into the argument entry.
650 arg.push_back (wp_id_arg);
652 // Push the data for the first argument into the m_arguments vector.
653 m_arguments.push_back (arg);
657 ~CommandObjectWatchpointCommandList () {}
661 DoExecute (Args& command,
662 CommandReturnObject &result)
664 Target *target = m_interpreter.GetDebugger().GetSelectedTarget().get();
668 result.AppendError ("There is not a current executable; there are no watchpoints for which to list commands");
669 result.SetStatus (eReturnStatusFailed);
673 const WatchpointList &watchpoints = target->GetWatchpointList();
674 size_t num_watchpoints = watchpoints.GetSize();
676 if (num_watchpoints == 0)
678 result.AppendError ("No watchpoints exist for which to list commands");
679 result.SetStatus (eReturnStatusFailed);
683 if (command.GetArgumentCount() == 0)
685 result.AppendError ("No watchpoint specified for which to list the commands");
686 result.SetStatus (eReturnStatusFailed);
690 std::vector<uint32_t> valid_wp_ids;
691 if (!CommandObjectMultiwordWatchpoint::VerifyWatchpointIDs(target, command, valid_wp_ids))
693 result.AppendError("Invalid watchpoints specification.");
694 result.SetStatus(eReturnStatusFailed);
698 result.SetStatus(eReturnStatusSuccessFinishNoResult);
699 const size_t count = valid_wp_ids.size();
700 for (size_t i = 0; i < count; ++i)
702 uint32_t cur_wp_id = valid_wp_ids.at (i);
703 if (cur_wp_id != LLDB_INVALID_WATCH_ID)
705 Watchpoint *wp = target->GetWatchpointList().FindByID (cur_wp_id).get();
709 const WatchpointOptions *wp_options = wp->GetOptions();
712 // Get the callback baton associated with the current watchpoint.
713 const Baton *baton = wp_options->GetBaton();
716 result.GetOutputStream().Printf ("Watchpoint %u:\n", cur_wp_id);
717 result.GetOutputStream().IndentMore ();
718 baton->GetDescription(&result.GetOutputStream(), eDescriptionLevelFull);
719 result.GetOutputStream().IndentLess ();
723 result.AppendMessageWithFormat ("Watchpoint %u does not have an associated command.\n",
727 result.SetStatus (eReturnStatusSuccessFinishResult);
731 result.AppendErrorWithFormat("Invalid watchpoint ID: %u.\n", cur_wp_id);
732 result.SetStatus (eReturnStatusFailed);
737 return result.Succeeded();
741 //-------------------------------------------------------------------------
742 // CommandObjectWatchpointCommand
743 //-------------------------------------------------------------------------
745 CommandObjectWatchpointCommand::CommandObjectWatchpointCommand (CommandInterpreter &interpreter) :
746 CommandObjectMultiword (interpreter,
748 "A set of commands for adding, removing and examining bits of code to be executed when the watchpoint is hit (watchpoint 'commmands').",
749 "command <sub-command> [<sub-command-options>] <watchpoint-id>")
751 CommandObjectSP add_command_object (new CommandObjectWatchpointCommandAdd (interpreter));
752 CommandObjectSP delete_command_object (new CommandObjectWatchpointCommandDelete (interpreter));
753 CommandObjectSP list_command_object (new CommandObjectWatchpointCommandList (interpreter));
755 add_command_object->SetCommandName ("watchpoint command add");
756 delete_command_object->SetCommandName ("watchpoint command delete");
757 list_command_object->SetCommandName ("watchpoint command list");
759 LoadSubCommand ("add", add_command_object);
760 LoadSubCommand ("delete", delete_command_object);
761 LoadSubCommand ("list", list_command_object);
764 CommandObjectWatchpointCommand::~CommandObjectWatchpointCommand ()