Diff 366494

lldb/docs/conf.py

Show All 23 Lines	if not building_man_page:
# add these directories to sys.path here. If the directory is relative to the		# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.		# documentation root, use os.path.abspath to make it absolute, like shown here.

# Add the current directory that contains the mock _lldb native module which		# Add the current directory that contains the mock _lldb native module which
# is imported by the `lldb` module.		# is imported by the `lldb` module.
sys.path.insert(0, os.path.abspath("."))		sys.path.insert(0, os.path.abspath("."))
# Add the build directory that contains the `lldb` module. LLDB_SWIG_MODULE is		# Add the build directory that contains the `lldb` module. LLDB_SWIG_MODULE is
# set by CMake.		# set by CMake.
sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE"))		sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE"))

		JDevlieghereUnsubmitted Not Done Reply Inline Actions Why is this necessary? It sounds like CMake should be setting this variable. JDevlieghere: Why is this necessary? It sounds like CMake should be setting this variable.
		siger-youngAuthorUnsubmitted Done Reply Inline Actions At the beginning, I was using `ninja lldb-docs-html` to build the docs. But it seems that it will build all of the docs each time it runs. It wastes some time, so I turn to `sphinx-build` command to build it, thus the env might become `None`. If extension `sphinx_tabs.tabs` is added, `None` value in `sys.path` will affect its importing. siger-young: At the beginning, I was using `ninja lldb-docs-html` to build the docs. But it seems that it…
# Put the generated Python API documentation in the 'python_api' folder. This		# Put the generated Python API documentation in the 'python_api' folder. This
# also defines the URL these files will have in the generated website.		# also defines the URL these files will have in the generated website.
automodapi_toctreedirnm = 'python_api'		automodapi_toctreedirnm = 'python_api'

		# Disable sphinx-tabs tab closing feature.
		sphinx_tabs_disable_tab_closing = True

# -- General configuration -----------------------------------------------------		# -- General configuration -----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.		# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'		#needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be extensions		# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.		# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx']		extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx', 'sphinx_tabs.tabs']

# Unless we only generate the basic manpage we need the plugin for generating		# Unless we only generate the basic manpage we need the plugin for generating
# the Python API documentation.		# the Python API documentation.
if not building_man_page:		if not building_man_page:
extensions.append('sphinx_automodapi.automodapi')		extensions.append('sphinx_automodapi.automodapi')

# Add any paths that contain templates here, relative to this directory.		# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']		templates_path = ['_templates']

# The suffix of source filenames.		# The suffix of source filenames.
source_suffix = {		source_suffix = {
'.rst': 'restructuredtext',		'.rst': 'restructuredtext',
}		}

try:		try:
import recommonmark		import recommonmark
except ImportError:		except ImportError:
# manpages do not use any .md sources		# manpages do not use any .md sources
if not building_man_page:		if not building_man_page:
raise		raise
else:		else:
import sphinx		import sphinx
if sphinx.version_info >= (3, 0):		if sphinx.version_info >= (3, 0):
# This requires 0.5 or later.		# This requires 0.5 or later.
extensions.append('recommonmark')		extensions.append('recommonmark')
else:		else:
source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}		source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
source_suffix['.md'] = 'markdown'		source_suffix['.md'] = 'markdown'

		JDevlieghereUnsubmitted Not Done Reply Inline Actions Unrelated change? JDevlieghere: Unrelated change?
		siger-youngAuthorUnsubmitted Done Reply Inline Actions Yes, it's unrelated. siger-young: Yes, it's unrelated.
# The encoding of source files.		# The encoding of source files.
#source_encoding = 'utf-8-sig'		#source_encoding = 'utf-8-sig'

# The master toctree document.		# The master toctree document.
master_doc = 'index'		master_doc = 'index'

# General information about the project.		# General information about the project.
project = u'LLDB'		project = u'LLDB'
▲ Show 20 Lines • Show All 89 Lines • ▼ Show 20 Lines
# relative to this directory. They are copied after the builtin static files,		# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".		# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']		html_static_path = ['_static']

html_context = {		html_context = {
'css_files': [		'css_files': [
'_static/lldb.css'		'_static/lldb.css'
],		],
}		}

		JDevlieghereUnsubmitted Not Done Reply Inline Actions Why is this necessary? JDevlieghere: Why is this necessary?
		siger-youngAuthorUnsubmitted Done Reply Inline Actions When I built the docs using the `html_context`, the final pages only include `lldb.css`, missing files from theme e.g. `alabaster.css`. siger-young: When I built the docs using the `html_context`, the final pages only include `lldb.css`…
		JDevlieghereUnsubmitted Not Done Reply Inline Actions Does this not break building the docs with `ninja lldb-docs-html`? JDevlieghere: Does this not break building the docs with `ninja lldb-docs-html`?
html_extra_path = ['.htaccess']		html_extra_path = ['.htaccess']

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,		# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.		# using the given strftime format.
html_last_updated_fmt = '%b %d, %Y'		html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to		# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.		# typographically correct entities.
▲ Show 20 Lines • Show All 108 Lines • ▼ Show 20 Lines
# -- Options for Texinfo output ------------------------------------------------		# -- Options for Texinfo output ------------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples		# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,		# (source start file, target name, title, author,
# dir menu entry, description, category)		# dir menu entry, description, category)
texinfo_documents = [		texinfo_documents = [
('index', 'LLDB', u'LLDB Documentation',		('index', 'LLDB', u'LLDB Documentation',
u'The LLDB Team', 'LLDB', 'One line description of project.',		u'The LLDB Team', 'LLDB', 'One line description of project.',
'Miscellaneous'),		'Miscellaneous'),
]		]
		JDevlieghereUnsubmitted Not Done Reply Inline Actions Unrelated whitespace change? JDevlieghere: Unrelated whitespace change?
		siger-youngAuthorUnsubmitted Done Reply Inline Actions Yes. siger-young: Yes.

# Documents to append as an appendix to all manuals.		# Documents to append as an appendix to all manuals.
#texinfo_appendices = []		#texinfo_appendices = []

# If false, no module index is generated.		# If false, no module index is generated.
#texinfo_domain_indices = True		#texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.		# How to display URL addresses: 'footnote', 'no', or 'inline'.
Show All 34 Lines

lldb/docs/index.rst

Show First 20 Lines • Show All 127 Lines • ▼ Show 20 Lines	.. toctree::
:caption: Use & Extension		:caption: Use & Extension

use/tutorial		use/tutorial
use/map		use/map
use/formatting		use/formatting
use/variable		use/variable
use/symbolication		use/symbolication
use/symbols		use/symbols
use/python		use/scripting-example
use/python-reference		use/scripting-reference
use/remote		use/remote
use/qemu-testing		use/qemu-testing
use/troubleshooting		use/troubleshooting
use/links		use/links

.. toctree::		.. toctree::
:hidden:		:hidden:
:maxdepth: 1		:maxdepth: 1
Show All 37 Lines

lldb/docs/use/python-reference.rst

This file was moved to lldb/docs/use/scripting-reference.rst.

lldb/docs/use/python.rst

This file was deleted.

	Python Scripting
	================

	LLDB has been structured from the beginning to be scriptable in two
	ways -- a Unix Python session can initiate/run a debug session
	non-interactively using LLDB; and within the LLDB debugger tool, Python
	scripts can be used to help with many tasks, including inspecting
	program data, iterating over containers and determining if a breakpoint
	should stop execution or continue. This document will show how to do
	some of these things by going through an example, explaining how to use
	Python scripting to find a bug in a program that searches for text in a
	large binary tree.

	.. contents::
	:local:

	The Test Program and Input
	--------------------------

	We have a simple C program (dictionary.c) that reads in a text file,
	and stores all the words from the file in a Binary Search Tree, sorted
	alphabetically. It then enters a loop prompting the user for a word,
	searching for the word in the tree (using Binary Search), and reporting
	to the user whether or not it found the word in the tree.

	The input text file we are using to test our program contains the text
	for William Shakespeare's famous tragedy "Romeo and Juliet".

	The Bug
	-------

	When we try running our program, we find there is a problem. While it
	successfully finds some of the words we would expect to find, such as
	"love" or "sun", it fails to find the word "Romeo", which MUST be in
	the input text file:

	::

	% ./dictionary Romeo-and-Juliet.txt
	Dictionary loaded.
	Enter search word: love
	Yes!
	Enter search word: sun
	Yes!
	Enter search word: Romeo
	No!
	Enter search word: ^D
	%

	Using Depth First Search
	------------------------

	Our first job is to determine if the word "Romeo" actually got inserted
	into the tree or not. Since "Romeo and Juliet" has thousands of words,
	trying to examine our binary search tree by hand is completely
	impractical. Therefore we will write a Python script to search the tree
	for us. We will write a recursive Depth First Search function that
	traverses the entire tree searching for a word, and maintaining
	information about the path from the root of the tree to the current
	node. If it finds the word in the tree, it returns the path from the
	root to the node containing the word. This is what our DFS function in
	Python would look like, with line numbers added for easy reference in
	later explanations:

	::

	1: def DFS (root, word, cur_path):
	2: root_word_ptr = root.GetChildMemberWithName ("word")
	3: left_child_ptr = root.GetChildMemberWithName ("left")
	4: right_child_ptr = root.GetChildMemberWithName ("right")
	5: root_word = root_word_ptr.GetSummary()
	6: end = len (root_word) - 1
	7: if root_word[0] == '"' and root_word[end] == '"':
	8: root_word = root_word[1:end]
	9: end = len (root_word) - 1
	10: if root_word[0] == '\'' and root_word[end] == '\'':
	11: root_word = root_word[1:end]
	12: if root_word == word:
	13: return cur_path
	14: elif word < root_word:
	15: if left_child_ptr.GetValue() == None:
	16: return ""
	17: else:
	18: cur_path = cur_path + "L"
	19: return DFS (left_child_ptr, word, cur_path)
	20: else:
	21: if right_child_ptr.GetValue() == None:
	22: return ""
	23: else:
	24: cur_path = cur_path + "R"
	25: return DFS (right_child_ptr, word, cur_path)


	Accessing & Manipulating Program Variables
	------------------------------------------

	Before we can call any Python function on any of our program's
	variables, we need to get the variable into a form that Python can
	access. To show you how to do this we will look at the parameters for
	the DFS function. The first parameter is going to be a node in our
	binary search tree, put into a Python variable. The second parameter is
	the word we are searching for (a string), and the third parameter is a
	string representing the path from the root of the tree to our current
	node.

	The most interesting parameter is the first one, the Python variable
	that needs to contain a node in our search tree. How can we take a
	variable out of our program and put it into a Python variable? What
	kind of Python variable will it be? The answers are to use the LLDB API
	functions, provided as part of the LLDB Python module. Running Python
	from inside LLDB, LLDB will automatically give us our current frame
	object as a Python variable, "lldb.frame". This variable has the type
	`SBFrame` (see the LLDB API for more information about `SBFrame`
	objects). One of the things we can do with a frame object, is to ask it
	to find and return its local variable. We will call the API function
	`SBFrame.FindVariable` on the lldb.frame object to give us our dictionary
	variable as a Python variable:

	::

	root = lldb.frame.FindVariable ("dictionary")

	The line above, executed in the Python script interpreter in LLDB, asks the
	current frame to find the variable named "dictionary" and return it. We then
	store the returned value in the Python variable named "root". This answers the
	question of HOW to get the variable, but it still doesn't explain WHAT actually
	gets put into "root". If you examine the LLDB API, you will find that the
	`SBFrame` method "FindVariable" returns an object of type `SBValue`. `SBValue`
	objects are used, among other things, to wrap up program variables and values.
	There are many useful methods defined in the `SBValue` class to allow you to get
	information or children values out of SBValues. For complete information, see
	the header file SBValue.h. The `SBValue` methods that we use in our DFS function
	are ``GetChildMemberWithName()``, ``GetSummary()``, and ``GetValue()``.


	Explaining DFS Script in Detail
	-------------------------------

	Before diving into the details of this code, it would be best to give a
	high-level overview of what it does. The nodes in our binary search tree were
	defined to have type ``tree_node *``, which is defined as:

	::

	typedef struct tree_node
	{
	const char *word;
	struct tree_node *left;
	struct tree_node *right;
	} tree_node;

	Lines 2-11 of DFS are getting data out of the current tree node and getting
	ready to do the actual search; lines 12-25 are the actual depth-first search.
	Lines 2-4 of our DFS function get the word, left and right fields out of the
	current node and store them in Python variables. Since root_word_ptr is a
	pointer to our word, and we want the actual word, line 5 calls GetSummary() to
	get a string containing the value out of the pointer. Since GetSummary() adds
	quotes around its result, lines 6-11 strip surrounding quotes off the word.

	Line 12 checks to see if the word in the current node is the one we are
	searching for. If so, we are done, and line 13 returns the current path.
	Otherwise, line 14 checks to see if we should go left (search word comes before
	the current word). If we decide to go left, line 15 checks to see if the left
	pointer child is NULL ("None" is the Python equivalent of NULL). If the left
	pointer is NULL, then the word is not in this tree and we return an empty path
	(line 16). Otherwise, we add an "L" to the end of our current path string, to
	indicate we are going left (line 18), and then recurse on the left child (line
	19). Lines 20-25 are the same as lines 14-19, except for going right rather
	than going left.

	One other note: Typing something as long as our DFS function directly into the
	interpreter can be difficult, as making a single typing mistake means having to
	start all over. Therefore we recommend doing as we have done: Writing your
	longer, more complicated script functions in a separate file (in this case
	tree_utils.py) and then importing it into your LLDB Python interpreter.


	The DFS Script in Action
	------------------------

	At this point we are ready to use the DFS function to see if the word "Romeo"
	is in our tree or not. To actually use it in LLDB on our dictionary program,
	you would do something like this:

	::

	% lldb
	(lldb) process attach -n "dictionary"
	Architecture set to: x86_64.
	Process 521 stopped
	* thread #1: tid = 0x2c03, 0x00007fff86c8bea0 libSystem.B.dylib`read$NOCANCEL + 8, stop reason = signal SIGSTOP
	frame #0: 0x00007fff86c8bea0 libSystem.B.dylib`read$NOCANCEL + 8
	(lldb) breakpoint set -n find_word
	Breakpoint created: 1: name = 'find_word', locations = 1, resolved = 1
	(lldb) continue
	Process 521 resuming
	Process 521 stopped
	* thread #1: tid = 0x2c03, 0x0000000100001830 dictionary`find_word + 16
	at dictionary.c:105, stop reason = breakpoint 1.1
	frame #0: 0x0000000100001830 dictionary`find_word + 16 at dictionary.c:105
	102 int
	103 find_word (tree_node dictionary, char word)
	104 {
	-> 105 if (!word \|\| !dictionary)
	106 return 0;
	107
	108 int compare_value = strcmp (word, dictionary->word);
	(lldb) script
	Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
	>>> import tree_utils
	>>> root = lldb.frame.FindVariable ("dictionary")
	>>> current_path = ""
	>>> path = tree_utils.DFS (root, "Romeo", current_path)
	>>> print path
	LLRRL
	>>> ^D
	(lldb)

	The first bit of code above shows starting lldb, attaching to the dictionary
	program, and getting to the find_word function in LLDB. The interesting part
	(as far as this example is concerned) begins when we enter the script command
	and drop into the embedded interactive Python interpreter. We will go over this
	Python code line by line. The first line

	::

	import tree_utils


	imports the file where we wrote our DFS function, tree_utils.py, into Python.
	Notice that to import the file we leave off the ".py" extension. We can now
	call any function in that file, giving it the prefix "tree_utils.", so that
	Python knows where to look for the function. The line

	::

	root = lldb.frame.FindVariable ("dictionary")


	gets our program variable "dictionary" (which contains the binary search tree)
	and puts it into the Python variable "root". See Accessing & Manipulating
	Program Variables in Python above for more details about how this works. The
	next line is

	::

	current_path = ""

	This line initializes the current_path from the root of the tree to our current
	node. Since we are starting at the root of the tree, our current path starts as
	an empty string. As we go right and left through the tree, the DFS function
	will append an 'R' or an 'L' to the current path, as appropriate. The line

	::

	path = tree_utils.DFS (root, "Romeo", current_path)

	calls our DFS function (prefixing it with the module name so that Python can
	find it). We pass in our binary tree stored in the variable root, the word we
	are searching for, and our current path. We assign whatever path the DFS
	function returns to the Python variable path.

	Finally, we want to see if the word was found or not, and if so we want to see
	the path through the tree to the word. So we do

	::

	print path

	From this we can see that the word "Romeo" was indeed found in the tree, and
	the path from the root of the tree to the node containing "Romeo" is
	left-left-right-right-left.

	Using Breakpoint Command Scripts
	--------------------------------

	We are halfway to figuring out what the problem is. We know the word we are
	looking for is in the binary tree, and we know exactly where it is in the
	binary tree. Now we need to figure out why our binary search algorithm is not
	finding the word. We will do this using breakpoint command scripts.

	The idea is as follows. The binary search algorithm has two main decision
	points: the decision to follow the right branch; and, the decision to follow
	the left branch. We will set a breakpoint at each of these decision points, and
	attach a Python breakpoint command script to each breakpoint. The breakpoint
	commands will use the global path Python variable that we got from our DFS
	function. Each time one of these decision breakpoints is hit, the script will
	compare the actual decision with the decision the front of the path variable
	says should be made (the first character of the path). If the actual decision
	and the path agree, then the front character is stripped off the path, and
	execution is resumed. In this case the user never even sees the breakpoint
	being hit. But if the decision differs from what the path says it should be,
	then the script prints out a message and does NOT resume execution, leaving the
	user sitting at the first point where a wrong decision is being made.

	Python Breakpoint Command Scripts Are Not What They Seem
	--------------------------------------------------------

	What do we mean by that? When you enter a Python breakpoint command in LLDB, it
	appears that you are entering one or more plain lines of Python. BUT LLDB then
	takes what you entered and wraps it into a Python FUNCTION (just like using the
	"def" Python command). It automatically gives the function an obscure, unique,
	hard-to-stumble-across function name, and gives it two parameters: frame and
	bp_loc. When the breakpoint gets hit, LLDB wraps up the frame object where the
	breakpoint was hit, and the breakpoint location object for the breakpoint that
	was hit, and puts them into Python variables for you. It then calls the Python
	function that was created for the breakpoint command, and passes in the frame
	and breakpoint location objects.

	So, being practical, what does this mean for you when you write your Python
	breakpoint commands? It means that there are two things you need to keep in
	mind: 1. If you want to access any Python variables created outside your
	script, you must declare such variables to be global. If you do not declare
	them as global, then the Python function will treat them as local variables,
	and you will get unexpected behavior. 2. All Python breakpoint command scripts
	automatically have a frame and a bp_loc variable. The variables are pre-loaded
	by LLDB with the correct context for the breakpoint. You do not have to use
	these variables, but they are there if you want them.

	The Decision Point Breakpoint Commands
	--------------------------------------

	This is what the Python breakpoint command script would look like for the
	decision to go right:

	::

	global path
	if path[0] == 'R':
	path = path[1:]
	thread = frame.GetThread()
	process = thread.GetProcess()
	process.Continue()
	else:
	print "Here is the problem; going right, should go left!"
	Just as a reminder, LLDB is going to take this script and wrap it up in a function, like this:


	def some_unique_and_obscure_function_name (frame, bp_loc):
	global path
	if path[0] == 'R':
	path = path[1:]
	thread = frame.GetThread()
	process = thread.GetProcess()
	process.Continue()
	else:
	print "Here is the problem; going right, should go left!"

	LLDB will call the function, passing in the correct frame and breakpoint
	location whenever the breakpoint gets hit. There are several things to notice
	about this function. The first one is that we are accessing and updating a
	piece of state (the path variable), and actually conditioning our behavior
	based upon this variable. Since the variable was defined outside of our script
	(and therefore outside of the corresponding function) we need to tell Python
	that we are accessing a global variable. That is what the first line of the
	script does. Next we check where the path says we should go and compare it to
	our decision (recall that we are at the breakpoint for the decision to go
	right). If the path agrees with our decision, then we strip the first character
	off of the path.

	Since the decision matched the path, we want to resume execution. To do this we
	make use of the frame parameter that LLDB guarantees will be there for us. We
	use LLDB API functions to get the current thread from the current frame, and
	then to get the process from the thread. Once we have the process, we tell it
	to resume execution (using the Continue() API function).

	If the decision to go right does not agree with the path, then we do not resume
	execution. We allow the breakpoint to remain stopped (by doing nothing), and we
	print an informational message telling the user we have found the problem, and
	what the problem is.

	Actually Using The Breakpoint Commands
	--------------------------------------

	Now we will look at what happens when we actually use these breakpoint commands
	on our program. Doing a source list -n find_word shows us the function
	containing our two decision points. Looking at the code below, we see that we
	want to set our breakpoints on lines 113 and 115:

	::

	(lldb) source list -n find_word
	File: /Volumes/Data/HD2/carolinetice/Desktop/LLDB-Web-Examples/dictionary.c.
	101
	102 int
	103 find_word (tree_node dictionary, char word)
	104 {
	105 if (!word \|\| !dictionary)
	106 return 0;
	107
	108 int compare_value = strcmp (word, dictionary->word);
	109
	110 if (compare_value == 0)
	111 return 1;
	112 else if (compare_value < 0)
	113 return find_word (dictionary->left, word);
	114 else
	115 return find_word (dictionary->right, word);
	116 }
	117


	So, we set our breakpoints, enter our breakpoint command scripts, and see what happens:

	::

	(lldb) breakpoint set -l 113
	Breakpoint created: 2: file ='dictionary.c', line = 113, locations = 1, resolved = 1
	(lldb) breakpoint set -l 115
	Breakpoint created: 3: file ='dictionary.c', line = 115, locations = 1, resolved = 1
	(lldb) breakpoint command add -s python 2
	Enter your Python command(s). Type 'DONE' to end.
	> global path
	> if (path[0] == 'L'):
	> path = path[1:]
	> thread = frame.GetThread()
	> process = thread.GetProcess()
	> process.Continue()
	> else:
	> print "Here is the problem. Going left, should go right!"
	> DONE
	(lldb) breakpoint command add -s python 3
	Enter your Python command(s). Type 'DONE' to end.
	> global path
	> if (path[0] == 'R'):
	> path = path[1:]
	> thread = frame.GetThread()
	> process = thread.GetProcess()
	> process.Continue()
	> else:
	> print "Here is the problem. Going right, should go left!"
	> DONE
	(lldb) continue
	Process 696 resuming
	Here is the problem. Going right, should go left!
	Process 696 stopped
	* thread #1: tid = 0x2d03, 0x000000010000189f dictionary`find_word + 127 at dictionary.c:115, stop reason = breakpoint 3.1
	frame #0: 0x000000010000189f dictionary`find_word + 127 at dictionary.c:115
	112 else if (compare_value < 0)
	113 return find_word (dictionary->left, word);
	114 else
	-> 115 return find_word (dictionary->right, word);
	116 }
	117
	118 void
	(lldb)


	After setting our breakpoints, adding our breakpoint commands and continuing,
	we run for a little bit and then hit one of our breakpoints, printing out the
	error message from the breakpoint command. Apparently at this point in the
	tree, our search algorithm decided to go right, but our path says the node we
	want is to the left. Examining the word at the node where we stopped, and our
	search word, we see:

	::

	(lldb) expr dictionary->word
	(const char *) $1 = 0x0000000100100080 "dramatis"
	(lldb) expr word
	(char *) $2 = 0x00007fff5fbff108 "romeo"

	So the word at our current node is "dramatis", and the word we are searching
	for is "romeo". "romeo" comes after "dramatis" alphabetically, so it seems like
	going right would be the correct decision. Let's ask Python what it thinks the
	path from the current node to our word is:

	::

	(lldb) script print path
	LLRRL

	According to Python we need to go left-left-right-right-left from our current
	node to find the word we are looking for. Let's double check our tree, and see
	what word it has at that node:

	::

	(lldb) expr dictionary->left->left->right->right->left->word
	(const char *) $4 = 0x0000000100100880 "Romeo"

	So the word we are searching for is "romeo" and the word at our DFS location is
	"Romeo". Aha! One is uppercase and the other is lowercase: We seem to have a
	case conversion problem somewhere in our program (we do).

	This is the end of our example on how you might use Python scripting in LLDB to
	help you find bugs in your program.

	Source Files for The Example
	----------------------------

	The complete code for the Dictionary program (with case-conversion bug), the
	DFS function and other Python script examples (tree_utils.py) used for this
	example are available below.

	tree_utils.py - Example Python functions using LLDB's API, including DFS

	::

	"""
	# ===-- tree_utils.py ---------------------------------------- Python --===//
	#
	# The LLVM Compiler Infrastructure
	#
	# This file is distributed under the University of Illinois Open Source
	# License. See LICENSE.TXT for details.
	#
	# ===---------------------------------------------------------------------===//

	tree_utils.py - A set of functions for examining binary
	search trees, based on the example search tree defined in
	dictionary.c. These functions contain calls to LLDB API
	functions, and assume that the LLDB Python module has been
	imported.

	For a thorough explanation of how the DFS function works, and
	for more information about dictionary.c go to
	http://lldb.llvm.org/scripting.html
	"""


	def DFS(root, word, cur_path):
	"""
	Recursively traverse a binary search tree containing
	words sorted alphabetically, searching for a particular
	word in the tree. Also maintains a string representing
	the path from the root of the tree to the current node.
	If the word is found in the tree, return the path string.
	Otherwise return an empty string.

	This function assumes the binary search tree is
	the one defined in dictionary.c It uses LLDB API
	functions to examine and traverse the tree nodes.
	"""

	# Get pointer field values out of node 'root'

	root_word_ptr = root.GetChildMemberWithName("word")
	left_child_ptr = root.GetChildMemberWithName("left")
	right_child_ptr = root.GetChildMemberWithName("right")

	# Get the word out of the word pointer and strip off
	# surrounding quotes (added by call to GetSummary).

	root_word = root_word_ptr.GetSummary()
	end = len(root_word) - 1
	if root_word[0] == '"' and root_word[end] == '"':
	root_word = root_word[1:end]
	end = len(root_word) - 1
	if root_word[0] == '\'' and root_word[end] == '\'':
	root_word = root_word[1:end]

	# Main depth first search

	if root_word == word:
	return cur_path
	elif word < root_word:

	# Check to see if left child is NULL

	if left_child_ptr.GetValue() is None:
	return ""
	else:
	cur_path = cur_path + "L"
	return DFS(left_child_ptr, word, cur_path)
	else:

	# Check to see if right child is NULL

	if right_child_ptr.GetValue() is None:
	return ""
	else:
	cur_path = cur_path + "R"
	return DFS(right_child_ptr, word, cur_path)


	def tree_size(root):
	"""
	Recursively traverse a binary search tree, counting
	the nodes in the tree. Returns the final count.

	This function assumes the binary search tree is
	the one defined in dictionary.c It uses LLDB API
	functions to examine and traverse the tree nodes.
	"""
	if (root.GetValue is None):
	return 0

	if (int(root.GetValue(), 16) == 0):
	return 0

	left_size = tree_size(root.GetChildAtIndex(1))
	right_size = tree_size(root.GetChildAtIndex(2))

	total_size = left_size + right_size + 1
	return total_size


	def print_tree(root):
	"""
	Recursively traverse a binary search tree, printing out
	the words at the nodes in alphabetical order (the
	search order for the binary tree).

	This function assumes the binary search tree is
	the one defined in dictionary.c It uses LLDB API
	functions to examine and traverse the tree nodes.
	"""
	if (root.GetChildAtIndex(1).GetValue() is not None) and (
	int(root.GetChildAtIndex(1).GetValue(), 16) != 0):
	print_tree(root.GetChildAtIndex(1))

	print root.GetChildAtIndex(0).GetSummary()

	if (root.GetChildAtIndex(2).GetValue() is not None) and (
	int(root.GetChildAtIndex(2).GetValue(), 16) != 0):
	print_tree(root.GetChildAtIndex(2))


	dictionary.c - Sample dictionary program, with bug

	::

	//===-- dictionary.c ---------------------------------------------- C --===//
	//
	// The LLVM Compiler Infrastructure
	//
	// This file is distributed under the University of Illinois Open Source
	// License. See LICENSE.TXT for details.
	//
	//===---------------------------------------------------------------------===//
	#include <ctype.h>
	#include <stdio.h>
	#include <stdlib.h>
	#include <string.h>

	typedef struct tree_node {
	const char *word;
	struct tree_node *left;
	struct tree_node *right;
	} tree_node;

	/* Given a char*, returns a substring that starts at the first
	alphabet character and ends at the last alphabet character, i.e. it
	strips off beginning or ending quotes, punctuation, etc. */

	char strip(char *word) {
	char start = word;
	int len = strlen(start);
	char *end = start + len - 1;

	while ((start < end) && (!isalpha(start[0])))
	start++;

	while ((end > start) && (!isalpha(end[0])))
	end--;

	if (start > end)
	return NULL;

	end[1] = '\0';
	*word = start;

	return start;
	}

	/* Given a binary search tree (sorted alphabetically by the word at
	each node), and a new word, inserts the word at the appropriate
	place in the tree. */

	void insert(tree_node root, char word) {
	if (root == NULL)
	return;

	int compare_value = strcmp(word, root->word);

	if (compare_value == 0)
	return;

	if (compare_value < 0) {
	if (root->left != NULL)
	insert(root->left, word);
	else {
	tree_node new_node = (tree_node )malloc(sizeof(tree_node));
	new_node->word = strdup(word);
	new_node->left = NULL;
	new_node->right = NULL;
	root->left = new_node;
	}
	} else {
	if (root->right != NULL)
	insert(root->right, word);
	else {
	tree_node new_node = (tree_node )malloc(sizeof(tree_node));
	new_node->word = strdup(word);
	new_node->left = NULL;
	new_node->right = NULL;
	root->right = new_node;
	}
	}
	}

	/* Read in a text file and storea all the words from the file in a
	binary search tree. */

	void populate_dictionary(tree_node *dictionary, char filename) {
	FILE *in_file;
	char word[1024];

	in_file = fopen(filename, "r");
	if (in_file) {
	while (fscanf(in_file, "%s", word) == 1) {
	char *new_word = (strdup(word));
	new_word = strip(&new_word);
	if (*dictionary == NULL) {
	tree_node new_node = (tree_node )malloc(sizeof(tree_node));
	new_node->word = new_word;
	new_node->left = NULL;
	new_node->right = NULL;
	*dictionary = new_node;
	} else
	insert(*dictionary, new_word);
	}
	}
	}

	/* Given a binary search tree and a word, search for the word
	in the binary search tree. */

	int find_word(tree_node dictionary, char word) {
	if (!word \|\| !dictionary)
	return 0;

	int compare_value = strcmp(word, dictionary->word);

	if (compare_value == 0)
	return 1;
	else if (compare_value < 0)
	return find_word(dictionary->left, word);
	else
	return find_word(dictionary->right, word);
	}

	/* Print out the words in the binary search tree, in sorted order. */

	void print_tree(tree_node *dictionary) {
	if (!dictionary)
	return;

	if (dictionary->left)
	print_tree(dictionary->left);

	printf("%s\n", dictionary->word);

	if (dictionary->right)
	print_tree(dictionary->right);
	}

	int main(int argc, char **argv) {
	tree_node *dictionary = NULL;
	char buffer[1024];
	char *filename;
	int done = 0;

	if (argc == 2)
	filename = argv[1];

	if (!filename)
	return -1;

	populate_dictionary(&dictionary, filename);
	fprintf(stdout, "Dictionary loaded.\nEnter search word: ");
	while (!done && fgets(buffer, sizeof(buffer), stdin)) {
	char *word = buffer;
	int len = strlen(word);
	int i;

	for (i = 0; i < len; ++i)
	word[i] = tolower(word[i]);

	if ((len > 0) && (word[len - 1] == '\n')) {
	word[len - 1] = '\0';
	len = len - 1;
	}

	if (find_word(dictionary, word))
	fprintf(stdout, "Yes!\n");
	else
	fprintf(stdout, "No!\n");

	fprintf(stdout, "Enter search word: ");
	}

	fprintf(stdout, "\n");
	return 0;
	}


	The text for "Romeo and Juliet" can be obtained from the Gutenberg Project
	(http://www.gutenberg.org).

lldb/docs/use/scripting-example.rst

This file was added.

Scripting Example

=================

LLDB has been structured from the beginning to be scriptable in two

ways -- a Unix Python session can initiate/run a debug session

non-interactively using LLDB; and within the LLDB debugger tool, Python

scripts can be used to help with many tasks, including inspecting program

data, iterating over containers and determining if a breakpoint should

stop execution or continue.

This document will show how to do some of these things by going through an

example, explaining how to use scripting to find a bug in a program that

searches for text in a large binary tree.

You can check :doc:`/use/scripting-reference` if you want to learn more about

scripting features in LLDB.

.. contents::

:local:

The Test Program and Input

--------------------------

We have a simple C program (dictionary.c) that reads in a text file,

and stores all the words from the file in a Binary Search Tree, sorted

alphabetically. It then enters a loop prompting the user for a word,

searching for the word in the tree (using Binary Search), and reporting

to the user whether or not it found the word in the tree.

The input text file we are using to test our program contains the text

for William Shakespeare's famous tragedy "Romeo and Juliet".

The Bug

-------

When we try running our program, we find there is a problem. While it

successfully finds some of the words we would expect to find, such as

"love" or "sun", it fails to find the word "Romeo", which MUST be in

the input text file:

% ./dictionary Romeo-and-Juliet.txt

Dictionary loaded.

Enter search word: love

Yes!

Enter search word: sun

Yes!

Enter search word: Romeo

No!

Enter search word: ^D

Using Depth First Search

------------------------

Our first job is to determine if the word "Romeo" actually got inserted

into the tree or not. Since "Romeo and Juliet" has thousands of words,

trying to examine our binary search tree by hand is completely

impractical. Therefore we will write a Python script to search the tree

for us. We will write a recursive Depth First Search function that

traverses the entire tree searching for a word, and maintaining

information about the path from the root of the tree to the current

node. If it finds the word in the tree, it returns the path from the

root to the node containing the word. This is what our DFS function in

Python would look like, with line numbers added for easy reference in

later explanations:

.. tabs::

.. code-tab:: python

def DFS(root, word, cur_path):

root_word_ptr = root.GetChildMemberWithName("word")

left_child_ptr = root.GetChildMemberWithName("left")

right_child_ptr = root.GetChildMemberWithName("right")

root_word = root_word_ptr.GetSummary()

end = len root_word) - 1

if root_word[0] == '"' and root_word[end] == '"':

root_word = root_word[1:end]

end = len(root_word) - 1

if root_word[0] == '\'' and root_word[end] == '\'':

root_word = root_word[1:end]

if root_word == word:

return cur_path

elif word < root_word:

if left_child_ptr.GetValue() == None:

return ""

else:

cur_path = cur_path + "L"

return DFS(left_child_ptr, word, cur_path)

else:

if right_child_ptr.GetValue() == None:

return ""

else:

cur_path = cur_path + "R"

return DFS(right_child_ptr, word, cur_path)

.. code-tab:: lua

local function DFS(root, word, cur_path)

local root_word_ptr = root:GetChildMemberWithName("word")

local left_child_ptr = root:GetChildMemberWithName("left")

local right_child_ptr = root:GetChildMemberWithName("right")

local root_word = root_word_ptr:GetSummary()

local end_pos = #root_word

if root_word:sub(1, 1) == '"' and root_word:sub(end_pos, end_pos) == '"' then

root_word = root_word:sub(2, end_pos - 1)

end

end_pos = #root_word

if root_word:sub(1, 1) == '\'' and root_word:sub(end_pos, end_pos) == '\'' then

root_word = root_word:sub(2, end_pos - 1)

end

if root_word == word then

return cur_path

elseif word < root_word then

if not left_child_ptr:GetValue() then

return ""

else

cur_path = cur_path .. "L"

return DFS(left_child_ptr, word, cur_path)

end

else

if not right_child_ptr:GetValue() then

return ""

else

cur_path = cur_path .. "R"

return DFS(right_child_ptr, word, cur_path)

end

return { DFS = DFS }

Accessing & Manipulating Program Variables

------------------------------------------

Before we can call any Python function on any of our program's

variables, we need to get the variable into a form that Python can

access. To show you how to do this we will look at the parameters for

the DFS function. The first parameter is going to be a node in our

binary search tree, put into a Python variable. The second parameter is

the word we are searching for (a string), and the third parameter is a

string representing the path from the root of the tree to our current

node.

The most interesting parameter is the first one, the Python variable

that needs to contain a node in our search tree. How can we take a

variable out of our program and put it into a Python variable? What

kind of Python variable will it be? The answers are to use the LLDB API

functions, provided as part of the LLDB Python module. Running Python

from inside LLDB, LLDB will automatically give us our current frame

object as a Python variable, "lldb.frame". This variable has the type

`SBFrame` (see the LLDB API for more information about `SBFrame`

objects). One of the things we can do with a frame object, is to ask it

to find and return its local variable. We will call the API function

`SBFrame.FindVariable` on the lldb.frame object to give us our dictionary

variable as a Python variable:

.. tabs::

.. code-tab:: python

.. code-tab:: lua

.. tabs::

.. code-tab:: python

root = lldb.frame.FindVariable("dictionary")

.. code-tab:: lua

root = lldb.frame:FindVariable("dictionary")

The line above, executed in the Python script interpreter in LLDB, asks the

current frame to find the variable named "dictionary" and return it. We then

store the returned value in the Python variable named "root". This answers the

question of HOW to get the variable, but it still doesn't explain WHAT actually

gets put into "root". If you examine the LLDB API, you will find that the

`SBFrame` method "FindVariable" returns an object of type `SBValue`. `SBValue`

objects are used, among other things, to wrap up program variables and values.

There are many useful methods defined in the `SBValue` class to allow you to get

information or children values out of SBValues. For complete information, see

the header file SBValue.h. The `SBValue` methods that we use in our DFS function

are ``GetChildMemberWithName()``, ``GetSummary()``, and ``GetValue()``.

Explaining DFS Script in Detail

-------------------------------

Before diving into the details of this code, it would be best to give a

high-level overview of what it does. The nodes in our binary search tree were

defined to have type ``tree_node *``, which is defined as:

typedef struct tree_node

{

const char *word;

struct tree_node *left;

struct tree_node *right;

} tree_node;

.. tabs::

.. code-tab:: python

:linenos:

:emphasize-lines: 2-13

def DFS(root, word, cur_path):

# get members and value

root_word_ptr = root.GetChildMemberWithName("word")

left_child_ptr = root.GetChildMemberWithName("left")

right_child_ptr = root.GetChildMemberWithName("right")

root_word = root_word_ptr.GetSummary()

# strip off quotes

end = len(root_word) - 1

if root_word[0] == '"' and root_word[end] == '"':

root_word = root_word[1:end]

end = len(root_word) - 1

if root_word[0] == '\'' and root_word[end] == '\'':

root_word = root_word[1:end]

# actual DFS begins

if root_word == word:

# found, return current path

return cur_path

elif word < root_word:

if left_child_ptr.GetValue() == None:

# not found, empty path is returned

return ""

else:

# append "L" to current path

cur_path = cur_path + "L"

# recurse on the left child

return DFS(left_child_ptr, word, cur_path)

else:

if right_child_ptr.GetValue() == None:

# not found, empty path is returned

return ""

else:

# append "R" to current path

cur_path = cur_path + "R"

# recurse on the right child

return DFS(right_child_ptr, word, cur_path)

.. code-tab:: lua

:linenos:

:emphasize-lines: 2-15

local function DFS(root, word, cur_path)

-- get members and value

local root_word_ptr = root:GetChildMemberWithName("word")

local left_child_ptr = root:GetChildMemberWithName("left")

local right_child_ptr = root:GetChildMemberWithName("right")

local root_word = root_word_ptr:GetSummary()

-- strip off quotes

local end_pos = #root_word

if root_word:sub(1, 1) == '"' and root_word:sub(end_pos, end_pos) == '"' then

root_word = root_word:sub(2, end_pos - 1)

end

end_pos = #root_word

if root_word:sub(1, 1) == '\'' and root_word:sub(end_pos, end_pos) == '\'' then

root_word = root_word:sub(2, end_pos - 1)

end

-- actual DFS begins

if root_word == word then

-- found, return current path

return cur_path

elseif word < root_word then

if not left_child_ptr:GetValue() then

-- not found, empty path is returned

return ""

else

-- append "L" to current path

cur_path = cur_path .. "L"

-- recurse on the left child

return DFS(left_child_ptr, word, cur_path)

end

else

if not right_child_ptr:GetValue() then

-- not found, empty path is returned

return ""

else

-- append "R" to current path

cur_path = cur_path .. "R"

-- recurse on the right child

return DFS(right_child_ptr, word, cur_path)

end

return { DFS = DFS }

The emphasized lines in the above code are getting data out of the current tree

node and getting ready to do the actual search.

.. tabs::

.. code-tab:: python

:linenos:

:lineno-start: 2

# get members and value

root_word_ptr = root.GetChildMemberWithName("word")

left_child_ptr = root.GetChildMemberWithName("left")

right_child_ptr = root.GetChildMemberWithName("right")

root_word = root_word_ptr.GetSummary()

.. code-tab:: lua

:linenos:

:lineno-start: 2

-- get members and value

local root_word_ptr = root:GetChildMemberWithName("word")

local left_child_ptr = root:GetChildMemberWithName("left")

local right_child_ptr = root:GetChildMemberWithName("right")

local root_word = root_word_ptr:GetSummary()

This part of our DFS function get the word, left and right fields out of the

current node and store them in Python variables. Since ``root_word_ptr`` is a

pointer to our word, and we want the actual word, we need to call GetSummary()

to get a string containing the value out of the pointer.

.. tabs::

.. code-tab:: python

:linenos:

:lineno-start: 7

# strip off quotes

end = len(root_word) - 1

if root_word[0] == '"' and root_word[end] == '"':

root_word = root_word[1:end]

end = len(root_word) - 1

if root_word[0] == '\'' and root_word[end] == '\'':

root_word = root_word[1:end]

.. code-tab:: lua

:linenos:

:lineno-start: 7

-- strip off quotes

local end_pos = #root_word

if root_word:sub(1, 1) == '"' and root_word:sub(end_pos, end_pos) == '"' then

root_word = root_word:sub(2, end_pos - 1)

end

end_pos = #root_word

if root_word:sub(1, 1) == '\'' and root_word:sub(end_pos, end_pos) == '\'' then

root_word = root_word:sub(2, end_pos - 1)

end

Since GetSummary() adds quotes around its result, this part strips surrounding

quotes off the word.

.. tabs::

.. code-tab:: python

:linenos:

:lineno-start: 14

# actual DFS begins

if root_word == word:

# found, return current path

return cur_path

elif word < root_word:

if left_child_ptr.GetValue() == None:

# not found, empty path is returned

return ""

else:

# append "L" to current path

cur_path = cur_path + "L"

# recurse on the left child

return DFS(left_child_ptr, word, cur_path)

else:

if right_child_ptr.GetValue() == None:

# not found, empty path is returned

return ""

else:

# append "R" to current path

cur_path = cur_path + "R"

# recurse on the right child

return DFS(right_child_ptr, word, cur_path)

.. code-tab:: lua

:linenos:

:lineno-start: 16

-- actual DFS begins

if root_word == word then

-- found, return current path

return cur_path

elseif word < root_word then

if not left_child_ptr:GetValue() then

-- not found, empty path is returned

return ""

else

-- append "L" to current path

cur_path = cur_path .. "L"

-- recurse on the left child

return DFS(left_child_ptr, word, cur_path)

end

else

if not right_child_ptr:GetValue() then

-- not found, empty path is returned

return ""

else

-- append "R" to current path

cur_path = cur_path .. "R"

-- recurse on the right child

return DFS(right_child_ptr, word, cur_path)

end

Then it checks to see if the word in the current node is the one we are

searching for. If so, we are done, and the current path is returned.

Otherwise, it checks to see if we should go left (search word comes before

the current word). If we decide to go left, it checks to see if the left

pointer child is NULL ("None" is the Python equivalent of NULL, "nil" is the Lua

equivalent). If the left pointer is NULL, then the word is not in this tree and

we return an empty path. Otherwise, we add an "L" to the end of our current path

string, to indicate we are going left, and then recurse on the left child.

The final "else" part is the same as the previous, except for going right rather

than going left.

One other note: Typing something as long as our DFS function directly into the

interpreter can be difficult, as making a single typing mistake means having to

start all over. Therefore we recommend doing as we have done: Writing your

longer, more complicated script functions in a separate file (in this case

``tree_utils.py`` for Python, ``tree_utils.lua`` for Lua) and then importing it

into your LLDB Python interpreter.

The DFS Script in Action

------------------------

At this point we are ready to use the DFS function to see if the word "Romeo"

is in our tree or not. To actually use it in LLDB on our dictionary program,

you would do something like this:

.. tabs::

.. code-tab:: python

% lldb

(lldb) process attach -n "dictionary"

Process 95616 stopped

* thread #1, name = 'dictionary', stop reason = signal SIGSTOP

frame #0: 0x00007fcf4906a862 libc.so.6 __read + 18

libc.so.6 __read:

-> 0x7fcf4906a862 <+18>: cmpq $-0x1000, %rax ; imm = 0xF000

0x7fcf4906a868 <+24>: ja 0x7fcf4906a8c0 ; <+112>

0x7fcf4906a86a <+26>: retq

0x7fcf4906a86b <+27>: nopl (%rax,%rax)

Executable module set to "/home/test/Desktop/dictionary".

Architecture set to: x86_64-pc-linux-gnu.

(lldb) breakpoint set -n find_word

Breakpoint 1: where = dictionary find_word + 16 at dictionary.c:108:9, address = 0x000055f9ac1fa5c0

(lldb) continue

Process 95616 resuming

Process 95616 stopped

* thread #1, name = 'dictionary', stop reason = breakpoint 1.1

frame #0: 0x000055f9ac1fa5c0 dictionary find_word(dictionary=0x000055f9ae14b4b0, word="romeo") at dictionary.c:108:9

(lldb) script

Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.

>>> import tree_utils

>>> root = lldb.frame.FindVariable("dictionary")

>>> current_path = ""

>>> path = tree_utils.DFS(root, "Romeo", current_path)

>>> print(path)

>>> ^D

now exiting InteractiveConsole...

(lldb)

.. code-tab:: lua

:emphasize-lines: 21

% lldb

(lldb) process attach -n "dictionary"

Process 95616 stopped

* thread #1, name = 'dictionary', stop reason = signal SIGSTOP

frame #0: 0x00007fcf4906a862 libc.so.6 __read + 18

libc.so.6 __read:

-> 0x7fcf4906a862 <+18>: cmpq $-0x1000, %rax ; imm = 0xF000

0x7fcf4906a868 <+24>: ja 0x7fcf4906a8c0 ; <+112>

0x7fcf4906a86a <+26>: retq

0x7fcf4906a86b <+27>: nopl (%rax,%rax)

Executable module set to "/home/test/Desktop/dictionary".

Architecture set to: x86_64-pc-linux-gnu.

(lldb) breakpoint set -n find_word

Breakpoint 1: where = dictionary find_word + 16 at dictionary.c:108:9, address = 0x000055f9ac1fa5c0

(lldb) continue

Process 95616 resuming

Process 95616 stopped

* thread #1, name = 'dictionary', stop reason = breakpoint 1.1

frame #0: 0x000055f9ac1fa5c0 dictionary find_word(dictionary=0x000055f9ae14b4b0, word="romeo") at dictionary.c:108:9

(lldb) script -l lua --

>>> tree_utils = require("tree_utils")

>>> root = lldb.frame:FindVariable("dictionary")

>>> current_path = ""

>>> path = tree_utils.DFS(root, "Romeo", current_path)

>>> print(path)

>>> ^D

(lldb)

The first bit of code above shows starting lldb, attaching to the dictionary

program, and getting to the find_word function in LLDB. The interesting part

(as far as this example is concerned) begins when we enter the script command

and drop into the embedded interactive Python interpreter. We will go over this

Python code line by line. The first line

.. tabs::

.. code-tab:: python

import tree_utils

.. code-tab:: lua

tree_utils = require("tree_utils")

imports the file where we wrote our DFS function, tree_utils.py, into Python.

Notice that to import the file we leave off the ".py" extension. We can now

call any function in that file, giving it the prefix "tree_utils.", so that

Python knows where to look for the function. The line

.. tabs::

.. code-tab:: python

root = lldb.frame.FindVariable("dictionary")

.. code-tab:: lua

root = lldb.frame:FindVariable("dictionary")

gets our program variable "dictionary" (which contains the binary search tree)

and puts it into the Python variable "root". See Accessing & Manipulating

Program Variables in Python above for more details about how this works. The

next line is

current_path = ""

This line initializes the current_path from the root of the tree to our current

node. Since we are starting at the root of the tree, our current path starts as

an empty string. As we go right and left through the tree, the DFS function

will append an 'R' or an 'L' to the current path, as appropriate. The line

path = tree_utils.DFS(root, "Romeo", current_path)

calls our DFS function (prefixing it with the module name so that interpreter

can find it). We pass in our binary tree stored in the variable root, the word

we are searching for, and our current path. We assign whatever path the DFS

function returns to the variable path.

Finally, we want to see if the word was found or not, and if so we want to see

the path through the tree to the word. So we do

print(path)

From this we can see that the word "Romeo" was indeed found in the tree, and

the path from the root of the tree to the node containing "Romeo" is

left-left-right-right-left.

Using Breakpoint Command Scripts

--------------------------------

We are halfway to figuring out what the problem is. We know the word we are

looking for is in the binary tree, and we know exactly where it is in the

binary tree. Now we need to figure out why our binary search algorithm is not

finding the word. We will do this using breakpoint command scripts.

The idea is as follows. The binary search algorithm has two main decision

points: the decision to follow the right branch; and, the decision to follow

the left branch. We will set a breakpoint at each of these decision points, and

attach a Python breakpoint command script to each breakpoint. The breakpoint

commands will use the global ``path`` variable that we got from our DFS

function. Each time one of these decision breakpoints is hit, the script will

compare the actual decision with the decision the front of the path variable

says should be made (the first character of the path). If the actual decision

and the path agree, then the front character is stripped off the path, and

execution is resumed. In this case the user never even sees the breakpoint

being hit. But if the decision differs from what the path says it should be,

then the script prints out a message and does NOT resume execution, leaving the

user sitting at the first point where a wrong decision is being made.

Python Breakpoint Command Scripts Are Not What They Seem

--------------------------------------------------------

What do we mean by that? When you enter a Python breakpoint command in LLDB, it

appears that you are entering one or more plain lines of Python. BUT LLDB then

takes what you entered and wraps it into a Python FUNCTION (just like using the

"def" Python command). It automatically gives the function an obscure, unique,

hard-to-stumble-across function name, and gives it two parameters: frame and

bp_loc. When the breakpoint gets hit, LLDB wraps up the frame object where the

breakpoint was hit, and the breakpoint location object for the breakpoint that

was hit, and puts them into Python variables for you. It then calls the Python

function that was created for the breakpoint command, and passes in the frame

and breakpoint location objects.

So, being practical, what does this mean for you when you write your Python

breakpoint commands? It means that there are two things you need to keep in

mind: 1. If you want to access any Python variables created outside your

script, you must declare such variables to be global. If you do not declare

them as global, then the Python function will treat them as local variables,

and you will get unexpected behavior. 2. All Python breakpoint command scripts

automatically have a frame and a bp_loc variable. The variables are pre-loaded

by LLDB with the correct context for the breakpoint. You do not have to use

these variables, but they are there if you want them.

The Decision Point Breakpoint Commands

--------------------------------------

This is what the Python breakpoint command script would look like for the

decision to go right:

.. tabs::

.. code-tab:: python

global path

if path[0] == 'R':

path = path[1:]

thread = frame.GetThread()

process = thread.GetProcess()

process.Continue()

else:

print("Here is the problem; going right, should go left!")

.. code-tab:: lua

if path:sub(1, 1) == 'R' then

path = path:sub(2, #path)

thread = frame:GetThread()

process = thread:GetProcess()

process:Continue()

else

print("Here is the problem; going right, should go left!")

end

Just as a reminder, LLDB is going to take this script and wrap it up in a function, like this:

.. tabs::

.. code-tab:: python

def some_unique_and_obscure_function_name(frame, bp_loc):

global path

if path[0] == 'R':

path = path[1:]

thread = frame.GetThread()

process = thread.GetProcess()

process.Continue()

else:

print("Here is the problem; going right, should go left!")

.. code-tab:: lua

function some_unique_and_obscure_function_name(frame, bp_loc)

if path:sub(1, 1) == 'R' then

path = path:sub(2, #path)

thread = frame:GetThread()

process = thread:GetProcess()

process:Continue()

else

print("Here is the problem; going right, should go left!")

end

LLDB will call the function, passing in the correct frame and breakpoint

location whenever the breakpoint gets hit. There are several things to notice

about this function. The first one is that we are accessing and updating a

piece of state (the path variable), and actually conditioning our behavior

based upon this variable. Since the variable was defined outside of our script

(and therefore outside of the corresponding function) we need to tell Python

that we are accessing a global variable. That is what the first line of the

script does. Next we check where the path says we should go and compare it to

our decision (recall that we are at the breakpoint for the decision to go

right). If the path agrees with our decision, then we strip the first character

off of the path.

Since the decision matched the path, we want to resume execution. To do this we

make use of the frame parameter that LLDB guarantees will be there for us. We

use LLDB API functions to get the current thread from the current frame, and

then to get the process from the thread. Once we have the process, we tell it

to resume execution (using the Continue() API function).

If the decision to go right does not agree with the path, then we do not resume

execution. We allow the breakpoint to remain stopped (by doing nothing), and we

print an informational message telling the user we have found the problem, and

what the problem is.

Actually Using The Breakpoint Commands

--------------------------------------

Now we will look at what happens when we actually use these breakpoint commands

on our program. Doing a ``source list -n find_word -c 20`` shows us 20 lines of

the function containing our two decision points. Looking at the code below, we

see that we want to set our breakpoints on lines 116 and 118:

.. code-block:: python

:emphasize-lines: 17,19

(lldb) source list -n find_word -c 20

File: /home/test/Desktop/dictionary.c

102 }

103

104 /* Given a binary search tree and a word, search for the word

105 in the binary search tree. */

106

107 int find_word(tree_node *dictionary, char *word) {

108 if (!word || !dictionary)

109 return 0;

110

111 int compare_value = strcmp(word, dictionary->word);

112

113 if (compare_value == 0)

114 return 1;

115 else if (compare_value < 0)

116 return find_word(dictionary->left, word);

117 else

118 return find_word(dictionary->right, word);

119 }

120

121 /* Print out the words in the binary search tree, in sorted order. */

122

123 void print_tree(tree_node *dictionary) {

124 if (!dictionary)

So, we set our breakpoints, enter our breakpoint command scripts, and see what happens:

(lldb) breakpoint set -l 116

Breakpoint created: 2: file ='dictionary.c', line = 113, locations = 1, resolved = 1

(lldb) breakpoint set -l 118

Breakpoint created: 3: file ='dictionary.c', line = 115, locations = 1, resolved = 1

(lldb) breakpoint command add -s python 2

Enter your Python command(s). Type 'DONE' to end.

> global path

> if (path[0] == 'L'):

> path = path[1:]

> thread = frame.GetThread()

> process = thread.GetProcess()

> process.Continue()

> else:

> print "Here is the problem. Going left, should go right!"

> DONE

(lldb) breakpoint command add -s python 3

Enter your Python command(s). Type 'DONE' to end.

> global path

> if (path[0] == 'R'):

> path = path[1:]

> thread = frame.GetThread()

> process = thread.GetProcess()

> process.Continue()

> else:

> print "Here is the problem. Going right, should go left!"

> DONE

(lldb) continue

Process 696 resuming

Here is the problem. Going right, should go left!

Process 696 stopped

* thread #1: tid = 0x2d03, 0x000000010000189f dictionary`find_word + 127 at dictionary.c:115, stop reason = breakpoint 3.1

frame #0: 0x000000010000189f dictionary`find_word + 127 at dictionary.c:115

112 else if (compare_value < 0)

113 return find_word (dictionary->left, word);

114 else

-> 115 return find_word (dictionary->right, word);

116 }

117

118 void

(lldb)

After setting our breakpoints, adding our breakpoint commands and continuing,

we run for a little bit and then hit one of our breakpoints, printing out the

error message from the breakpoint command. Apparently at this point in the

tree, our search algorithm decided to go right, but our path says the node we

want is to the left. Examining the word at the node where we stopped, and our

search word, we see:

(lldb) expr dictionary->word

(const char *) $1 = 0x0000000100100080 "dramatis"

(lldb) expr word

(char *) $2 = 0x00007fff5fbff108 "romeo"

So the word at our current node is "dramatis", and the word we are searching

for is "romeo". "romeo" comes after "dramatis" alphabetically, so it seems like

going right would be the correct decision. Let's ask Python what it thinks the

path from the current node to our word is:

(lldb) script print(path)

LLRRL

According to Python we need to go left-left-right-right-left from our current

node to find the word we are looking for. Let's double check our tree, and see

what word it has at that node:

(lldb) expr dictionary->left->left->right->right->left->word

(const char *) $4 = 0x0000000100100880 "Romeo"

So the word we are searching for is "romeo" and the word at our DFS location is

"Romeo". Aha! One is uppercase and the other is lowercase: We seem to have a

case conversion problem somewhere in our program (we do).

This is the end of our example on how you might use Python scripting in LLDB to

help you find bugs in your program.

Source Files for The Example

----------------------------

The complete code for the Dictionary program (with case-conversion bug), the

DFS function and other Python script examples (tree_utils.py) used for this

tammelaUnsubmitted

Not Done

The complete code for the Dictionary program (with case-conversion bug), the

- DFS function and other Python script examples (tree_utils.py) used for this

+ DFS function and other script examples used for this

example are available below.

tammela:

example are available below.

tree_utils.py - Example Python functions using LLDB's API, including DFS

tree_utils.lua - Example Lua functions using LLDB's API, including DFS

.. tabs::

.. code-tab:: python

"""

# ===-- tree_utils.py ---------------------------------------*- Python -*-===//

# The LLVM Compiler Infrastructure

# This file is distributed under the University of Illinois Open Source

# License. See LICENSE.TXT for details.

# ===---------------------------------------------------------------------===//

tree_utils.py - A set of functions for examining binary

search trees, based on the example search tree defined in

dictionary.c. These functions contain calls to LLDB API

functions, and assume that the LLDB Python module has been

imported.

For a thorough explanation of how the DFS function works, and

for more information about dictionary.c go to

http://lldb.llvm.org/scripting.html

"""

def DFS(root, word, cur_path):

"""

Recursively traverse a binary search tree containing

words sorted alphabetically, searching for a particular

word in the tree. Also maintains a string representing

the path from the root of the tree to the current node.

If the word is found in the tree, return the path string.

Otherwise return an empty string.

This function assumes the binary search tree is

the one defined in dictionary.c It uses LLDB API

functions to examine and traverse the tree nodes.

"""

# Get pointer field values out of node 'root'

root_word_ptr = root.GetChildMemberWithName("word")

left_child_ptr = root.GetChildMemberWithName("left")

right_child_ptr = root.GetChildMemberWithName("right")

# Get the word out of the word pointer and strip off

# surrounding quotes (added by call to GetSummary).

root_word = root_word_ptr.GetSummary()

end = len(root_word) - 1

if root_word[0] == '"' and root_word[end] == '"':

root_word = root_word[1:end]

end = len(root_word) - 1

if root_word[0] == '\'' and root_word[end] == '\'':

root_word = root_word[1:end]

# Main depth first search

if root_word == word:

return cur_path

elif word < root_word:

# Check to see if left child is NULL

if left_child_ptr.GetValue() is None:

return ""

else:

cur_path = cur_path + "L"

return DFS(left_child_ptr, word, cur_path)

else:

# Check to see if right child is NULL

if right_child_ptr.GetValue() is None:

return ""

else:

cur_path = cur_path + "R"

return DFS(right_child_ptr, word, cur_path)

def tree_size(root):

"""

Recursively traverse a binary search tree, counting

the nodes in the tree. Returns the final count.

This function assumes the binary search tree is

the one defined in dictionary.c It uses LLDB API

functions to examine and traverse the tree nodes.

"""

if (root.GetValue is None):

return 0

if (int(root.GetValue(), 16) == 0):

return 0

left_size = tree_size(root.GetChildAtIndex(1))

right_size = tree_size(root.GetChildAtIndex(2))

total_size = left_size + right_size + 1

return total_size

def print_tree(root):

"""

Recursively traverse a binary search tree, printing out

the words at the nodes in alphabetical order (the

search order for the binary tree).

This function assumes the binary search tree is

the one defined in dictionary.c It uses LLDB API

functions to examine and traverse the tree nodes.

"""

if (root.GetChildAtIndex(1).GetValue() is not None) and (

int(root.GetChildAtIndex(1).GetValue(), 16) != 0):

print_tree(root.GetChildAtIndex(1))

print root.GetChildAtIndex(0).GetSummary()

if (root.GetChildAtIndex(2).GetValue() is not None) and (

int(root.GetChildAtIndex(2).GetValue(), 16) != 0):

print_tree(root.GetChildAtIndex(2))

.. code-tab:: lua

local function DFS(root, word, cur_path)

--[[

Recursively traverse a binary search tree containing

words sorted alphabetically, searching for a particular

word in the tree. Also maintains a string representing

the path from the root of the tree to the current node.

If the word is found in the tree, return the path string.

Otherwise return an empty string.

This function assumes the binary search tree is

the one defined in dictionary.c It uses LLDB API

functions to examine and traverse the tree nodes.

]]

-- Get pointer field values out of node 'root'

local root_word_ptr = root:GetChildMemberWithName("word")

local left_child_ptr = root:GetChildMemberWithName("left")

local right_child_ptr = root:GetChildMemberWithName("right")

-- Get the word out of the word pointer and strip off

-- surrounding quotes (added by call to GetSummary).

local root_word = root_word_ptr:GetSummary()

local end_pos = #root_word

if root_word:sub(1, 1) == '"' and root_word:sub(end_pos, end_pos) == '"' then

root_word = root_word:sub(2, end_pos - 1)

end

end_pos = #root_word

if root_word:sub(1, 1) == '\'' and root_word:sub(end_pos, end_pos) == '\'' then

root_word = root_word:sub(2, end_pos - 1)

end

-- Main depth first search

if root_word == word then

return cur_path

elseif word < root_word then

-- Check to see if left child is NULL

if not left_child_ptr:GetValue() then

return ""

else

cur_path = cur_path .. "L"

return DFS(left_child_ptr, word, cur_path)

end

else

-- Check to see if right child is NULL

if not right_child_ptr:GetValue() then

return ""

else

cur_path = cur_path .. "R"

return DFS(right_child_ptr, word, cur_path)

end

return { DFS = DFS }

dictionary.c - Sample dictionary program, with bug

.. code-block:: c

//===-- dictionary.c ---------------------------------------------*- C -*-===//

// The LLVM Compiler Infrastructure

// This file is distributed under the University of Illinois Open Source

// License. See LICENSE.TXT for details.

//===---------------------------------------------------------------------===//

#include <ctype.h>

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

typedef struct tree_node {

const char *word;

struct tree_node *left;

struct tree_node *right;

} tree_node;

/* Given a char*, returns a substring that starts at the first

alphabet character and ends at the last alphabet character, i.e. it

strips off beginning or ending quotes, punctuation, etc. */

char *strip(char **word) {

char *start = *word;

int len = strlen(start);

char *end = start + len - 1;

while ((start < end) && (!isalpha(start[0])))

start++;

while ((end > start) && (!isalpha(end[0])))

end--;

if (start > end)

return NULL;

end[1] = '\0';

*word = start;

return start;

}

/* Given a binary search tree (sorted alphabetically by the word at

each node), and a new word, inserts the word at the appropriate

place in the tree. */

void insert(tree_node *root, char *word) {

if (root == NULL)

return;

int compare_value = strcmp(word, root->word);

if (compare_value == 0)

return;

if (compare_value < 0) {

if (root->left != NULL)

insert(root->left, word);

else {

tree_node *new_node = (tree_node *)malloc(sizeof(tree_node));

new_node->word = strdup(word);

new_node->left = NULL;

new_node->right = NULL;

root->left = new_node;

}

} else {

if (root->right != NULL)

insert(root->right, word);

else {

tree_node *new_node = (tree_node *)malloc(sizeof(tree_node));

new_node->word = strdup(word);

new_node->left = NULL;

new_node->right = NULL;

root->right = new_node;

}

/* Read in a text file and storea all the words from the file in a

binary search tree. */

void populate_dictionary(tree_node **dictionary, char *filename) {

FILE *in_file;

char word[1024];

in_file = fopen(filename, "r");

if (in_file) {

while (fscanf(in_file, "%s", word) == 1) {

char *new_word = (strdup(word));

new_word = strip(&new_word);

if (*dictionary == NULL) {

tree_node *new_node = (tree_node *)malloc(sizeof(tree_node));

new_node->word = new_word;

new_node->left = NULL;

new_node->right = NULL;

*dictionary = new_node;

} else

insert(*dictionary, new_word);

}

/* Given a binary search tree and a word, search for the word

in the binary search tree. */

int find_word(tree_node *dictionary, char *word) {

if (!word || !dictionary)

return 0;

int compare_value = strcmp(word, dictionary->word);

if (compare_value == 0)

return 1;

else if (compare_value < 0)

return find_word(dictionary->left, word);

else

return find_word(dictionary->right, word);

}

/* Print out the words in the binary search tree, in sorted order. */

void print_tree(tree_node *dictionary) {

if (!dictionary)

return;

if (dictionary->left)

print_tree(dictionary->left);

printf("%s\n", dictionary->word);

if (dictionary->right)

print_tree(dictionary->right);

}

int main(int argc, char **argv) {

tree_node *dictionary = NULL;

char buffer[1024];

char *filename;

int done = 0;

if (argc == 2)

filename = argv[1];

if (!filename)

return -1;

populate_dictionary(&dictionary, filename);

fprintf(stdout, "Dictionary loaded.\nEnter search word: ");

while (!done && fgets(buffer, sizeof(buffer), stdin)) {

char *word = buffer;

int len = strlen(word);

int i;

for (i = 0; i < len; ++i)

word[i] = tolower(word[i]);

if ((len > 0) && (word[len - 1] == '\n')) {

word[len - 1] = '\0';

len = len - 1;

}

if (find_word(dictionary, word))

fprintf(stdout, "Yes!\n");

else

fprintf(stdout, "No!\n");

fprintf(stdout, "Enter search word: ");

}

fprintf(stdout, "\n");

return 0;

}

The text for "Romeo and Juliet" can be obtained from the Gutenberg Project

(https://www.gutenberg.org/files/1513/1513-0.txt).

lldb/docs/use/scripting-reference.rst

This file was moved from lldb/docs/use/python-reference.rst.

Python Reference		Scripting Reference
		tammelaUnsubmitted Not Done Reply Inline Actions I'm seeing some references to a "python script" when it should be really just "the following script" or something more neutral. A quick way to solve this is to search for [Pp]ython and try to rewrite the phrase into something generic tammela: I'm seeing some references to a "python script" when it should be really just "the following…
================		===================

The entire LLDB API is available as Python functions through a script bridging		Python can be used as a programmatic interface within the LLDB command
interface. This means the LLDB API's can be used directly from python either		interpreter (we refer to this for brevity as the embedded interpreter).
interactively or to build python apps that provide debugger features.

Additionally, Python can be used as a programmatic interface within the lldb
command interpreter (we refer to this for brevity as the embedded interpreter).
Of course, in this context it has full access to the LLDB API - with some		Of course, in this context it has full access to the LLDB API - with some
additional conveniences we will call out in the FAQ.		additional conveniences we will call out in the FAQ.

		Additionally, the entire LLDB API is available as Python functions through
		a script bridging interface. This means the LLDB API's can be used directly
		from Python either interactively or to build Python apps that provide debugger
		features.

		At present, Lua is experimentally available as an embedded interpreter in LLDB.
		Moreover, LLDB API is also visible to standalone Lua. Since some scripting
		features are still unavailable in Lua, there is no language switch tab on code
		blocks of unsupported features.

		If you want to use Lua interpreter, you should ensure that your LLDB is compiled
		with Lua support. See :doc:`Building </resources/build>` for instructions.

.. contents::		.. contents::
:local:		:local:

Documentation		Built-in Documentation
--------------		----------------------

The LLDB API is contained in a python module named lldb. A useful resource when		The LLDB API is contained in a Python module named ``lldb``. A useful resource
writing Python extensions is the lldb Python classes reference guide.		when writing Python extensions is the `lldb` Python classes reference guide.

The documentation is also accessible in an interactive debugger session with		The documentation is also accessible in an interactive debugger session with
the following command:		the following command:

::		::

(lldb) script help(lldb)		(lldb) script help(lldb)
Help on package lldb:		Help on package lldb:
Show All 20 Lines	(lldb) script help(lldb.SBFrame)
\| Represents one of the stack frames associated with a thread.		\| Represents one of the stack frames associated with a thread.
\| SBThread contains SBFrame(s). For example (from test/lldbutil.py),		\| SBThread contains SBFrame(s). For example (from test/lldbutil.py),
\|		\|
\| def print_stacktrace(thread, string_buffer = False):		\| def print_stacktrace(thread, string_buffer = False):
\| '''Prints a simple stack trace of this thread.'''		\| '''Prints a simple stack trace of this thread.'''
\|		\|
...		...

Or you can get help using any python object, here we use the lldb.process
		Or you can get help using any Python object, here we use the lldb.process
object which is a global variable in the lldb module which represents the		object which is a global variable in the lldb module which represents the
currently selected process:		currently selected process:

::		::

(lldb) script help(lldb.process)		(lldb) script help(lldb.process)
Help on SBProcess in module lldb object:		Help on SBProcess in module lldb object:

class SBProcess(__builtin__.object)		class SBProcess(__builtin__.object)
\| Represents the process associated with the target program.		\| Represents the process associated with the target program.
\|		\|
\| SBProcess supports thread iteration. For example (from test/lldbutil.py),		\| SBProcess supports thread iteration. For example (from test/lldbutil.py),
\|		\|
\| # ==================================================		\| # ==================================================
\| # Utility functions related to Threads and Processes		\| # Utility functions related to Threads and Processes
\| # ==================================================		\| # ==================================================
\|		\|
...		...

Embedded Python Interpreter		Embedded Script Interpreter
---------------------------		---------------------------

The embedded python interpreter can be accessed in a variety of ways from		The embedded script interpreter can be accessed in a variety of ways from
within LLDB. The easiest way is to use the lldb command script with no		within LLDB. The easiest way is to use the LLDB command ``script`` with no
arguments at the lldb command prompt:		arguments at the LLDB command prompt.

		By default, the embedded script interpreter is Python. To choose the language
		you prefer, you can specify default language via ``--script-language`` options
		when launching LLDB:

::		::

		$ lldb --script-language lua

		or pass a parameter to LLDB command ``script``.

		::

		(lldb) script -l lua --

		Language features are all available in the embedded script interpreter:

		.. tabs::
		.. code-tab:: python

(lldb) script		(lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.		Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> 2+3		>>> 2+3
5		5
>>> hex(12345)		>>> hex(12345)
'0x3039'		'0x3039'
>>>		>>>

This drops you into the embedded python interpreter. When running under the		.. code-tab:: lua
script command, lldb sets some convenience variables that give you quick access		:emphasize-lines: 1

		(lldb) script -l lua --
		>>> t = { 1, 2, 3 }
		>>> print(t[1])
		1
		>>> print(t[1] + t[2])
		3
		>>>

		This drops you into the embedded script interpreter. When running under the
		script command, LLDB sets some convenience variables that give you quick access
to the currently selected entities that characterize the program and debugger		to the currently selected entities that characterize the program and debugger
state. In each case, if there is no currently selected entity of the		state. In each case, if there is no currently selected entity of the
appropriate type, the variable's IsValid method will return false. These		appropriate type, the variable's IsValid method will return false. These
variables are:		variables are:

+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+		+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
\| Variable \| Type \| Equivalent \| Description \|		\| Variable \| Type \| Equivalent \| Description \|
+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+		+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
Show All 29 Lines

While extremely convenient, these variables have a couple caveats that you		While extremely convenient, these variables have a couple caveats that you
should be aware of. First of all, they hold the values of the selected objects		should be aware of. First of all, they hold the values of the selected objects
on entry to the embedded interpreter. They do not update as you use the LLDB		on entry to the embedded interpreter. They do not update as you use the LLDB
API's to change, for example, the currently selected stack frame or thread.		API's to change, for example, the currently selected stack frame or thread.

Moreover, they are only defined and meaningful while in the interactive Python		Moreover, they are only defined and meaningful while in the interactive Python
interpreter. There is no guarantee on their value in any other situation, hence		interpreter. There is no guarantee on their value in any other situation, hence
you should not use them when defining Python formatters, breakpoint scripts and		you should not use them when defining custom formatters, breakpoint scripts and
commands (or any other Python extension point that LLDB provides). For the		commands (or any other script extension point that LLDB provides). For the
latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or		latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or
`SBframe` instance and you can use the functions from the "Equivalent" column		`SBframe` instance and you can use the functions from the "Equivalent" column
to navigate between them.		to navigate between them.

As a rationale for such behavior, consider that lldb can run in a multithreaded		As a rationale for such behavior, consider that LLDB can run in a multithreaded
environment, and another thread might call the "script" command, changing the		environment, and another thread might call the "script" command, changing the
value out from under you.		value out from under you.

To get started with these objects and LLDB scripting, please note that almost		To get started with these objects and LLDB scripting, please note that almost
all of the lldb Python objects are able to briefly describe themselves when you		all of the lldb objects are able to briefly describe themselves when you pass
pass them to the Python print function:		them to ``print`` function:

::		.. tabs::
		.. code-tab:: python

(lldb) script		(lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.		Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> print lldb.debugger		>>> print lldb.debugger
Debugger (instance: "debugger_1", id: 1)		Debugger (instance: "debugger_1", id: 1)
>>> print lldb.target		>>> print lldb.target
a.out		a.out
>>> print lldb.process		>>> print lldb.process
SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out		SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out
>>> print lldb.thread		>>> print lldb.thread
SBThread: tid = 0x1f03		SBThread: tid = 0x1f03
>>> print lldb.frame		>>> print lldb.frame
frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16		frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16

		.. code-tab:: lua

Running a python script when a breakpoint gets hit		(lldb) script -l lua --
--------------------------------------------------		>>> print(lldb.debugger)
		Debugger (instance: "debugger_1", id: 1)
One very powerful use of the lldb Python API is to have a python script run		>>> print(lldb.target)
when a breakpoint gets hit. Adding python scripts to breakpoints provides a way		a.out
to create complex breakpoint conditions and also allows for smart logging and		>>> print(lldb.process)
data gathering.		SBProcess: pid = 3385871, state = stopped, threads = 1, executable = a.out
		>>> print(lldb.thread)
		thread #1: tid = 3385871, name = 'a.out', stop reason = breakpoint 1.1
		>>> print(lldb.frame)
		frame #0: 0x000055555555514f a.out main at test.c:5:3

		Running a script when a breakpoint gets hit
		-------------------------------------------

		One very powerful use of the LLDB API is to have a script run when a breakpoint
		gets hit. Adding python scripts to breakpoints provides a way to create complex
		breakpoint conditions and also allows for smart logging and data gathering.

When your process hits a breakpoint to which you have attached some python		When your process hits a breakpoint to which you have attached some python
code, the code is executed as the body of a function which takes three		code, the code is executed as the body of a function which takes three
arguments:		arguments:

::		.. tabs::
		.. code-tab:: python

def breakpoint_function_wrapper(frame, bp_loc, internal_dict):		def breakpoint_function_wrapper(frame, bp_loc, internal_dict):
# Your code goes here		# Your code goes here

		.. code-tab:: lua

		function breakpoint_function_wrapper(frame, bp_loc)
		-- Your code goes here

or:		or:

::		.. tabs::
		.. code-tab:: python

def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict):		def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict):
# Your code goes here		# Your code goes here

		.. code-tab:: lua

		function breakpoint_function_wrapper(frame, bp_loc, ...)
		-- Your code goes here

+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+		+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
\| Argument \| Type \| Description \|		\| Argument \| Type \| Description \|
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+		+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
\| `frame` \| `lldb.SBFrame` \| The current stack frame where the breakpoint got hit. \|		\| `frame` \| `lldb.SBFrame` \| The current stack frame where the breakpoint got hit. \|
\| \| \| The object will always be valid. \|		\| \| \| The object will always be valid. \|
\| \| \| This `frame` argument might not match the currently selected stack frame found in the `lldb` module global variable `lldb.frame`. \|		\| \| \| This `frame` argument might not match the currently selected stack frame found in the `lldb` module global variable `lldb.frame`. \|
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+		+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
\| `bp_loc` \| `lldb.SBBreakpointLocation` \| The breakpoint location that just got hit. Breakpoints are represented by `lldb.SBBreakpoint` \|		\| `bp_loc` \| `lldb.SBBreakpointLocation` \| The breakpoint location that just got hit. Breakpoints are represented by `lldb.SBBreakpoint` \|
\| \| \| objects. These breakpoint objects can have one or more locations. These locations \|		\| \| \| objects. These breakpoint objects can have one or more locations. These locations \|
\| \| \| are represented by `lldb.SBBreakpointLocation` objects. \|		\| \| \| are represented by `lldb.SBBreakpointLocation` objects. \|
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+		+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
\| `extra_args` \| `lldb.SBStructuredData` \| `Optional` If your breakpoint callback function takes this extra parameter, then when the callback gets added to a breakpoint, its \|		\| `extra_args` \| `lldb.SBStructuredData` \| `Optional` If your breakpoint callback function takes this extra parameter, then when the callback gets added to a breakpoint, its \|
\| \| \| contents can parametrize this use of the callback. For instance, instead of writing a callback that stops when the caller is "Foo", \|		\| \| \| contents can parametrize this use of the callback. For instance, instead of writing a callback that stops when the caller is "Foo", \|
\| \| \| you could take the function name from a field in the `extra_args`, making the callback more general. The `-k` and `-v` options \|		\| \| \| you could take the function name from a field in the `extra_args`, making the callback more general. The `-k` and `-v` options \|
\| \| \| to `breakpoint command add` will be passed as a Dictionary in the `extra_args` parameter, or you can provide it with the SB API's. \|		\| \| \| to `breakpoint command add` will be passed as a Dictionary in the `extra_args` parameter, or you can provide it with the SB API's. \|
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+		+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
\| `internal_dict` \| `dict` \| The python session dictionary as a standard python dictionary object. \|		\| `internal_dict` \| `dict` \| The Python session dictionary as a standard python dictionary object. \|
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+		+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+

Optionally, a Python breakpoint command can return a value. Returning False		Optionally, a Python breakpoint command can return a value. Returning False
tells LLDB that you do not want to stop at the breakpoint. Any other return		tells LLDB that you do not want to stop at the breakpoint. Any other return
value (including None or leaving out the return statement altogether) is akin		value (including None or leaving out the return statement altogether) is akin
to telling LLDB to actually stop at the breakpoint. This can be useful in		to telling LLDB to actually stop at the breakpoint. This can be useful in
situations where a breakpoint only needs to stop the process when certain		situations where a breakpoint only needs to stop the process when certain
conditions are met, and you do not want to inspect the program state manually		conditions are met, and you do not want to inspect the program state manually
Show All 16 Lines
location so we won't count this function again; then log some info and continue		location so we won't count this function again; then log some info and continue
the process.		the process.

Note we also have to initialize our counter, which we do with the simple		Note we also have to initialize our counter, which we do with the simple
one-line version of the script command.		one-line version of the script command.

Here is the code:		Here is the code:

::		.. tabs::
		.. code-tab:: python

(lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib		(lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib
Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223		Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
(lldb) script counter = 0		(lldb) script counter = 0
(lldb) breakpoint command add --script-type python 1		(lldb) breakpoint command add --script-type python 1
Enter your Python command(s). Type 'DONE' to end.		Enter your Python command(s). Type 'DONE' to end.
> # Increment our counter. Since we are in a function, this must be a global python variable		> # Increment our counter. Since we are in a function, this must be a global python variable
> global counter		> global counter
> counter += 1		> counter += 1
> # Get the name of the function		> # Get the name of the function
> name = frame.GetFunctionName()		> name = frame.GetFunctionName()
> # Print the order and the function name		> # Print the order and the function name
> print '[%i] %s' % (counter, name)		> print '[%i] %s' % (counter, name)
> # Disable the current breakpoint location so it doesn't get hit again		> # Disable the current breakpoint location so it doesn't get hit again
> bp_loc.SetEnabled(False)		> bp_loc.SetEnabled(False)
> # No need to stop here		> # No need to stop here
> return False		> return False
> DONE		> DONE

The breakpoint command add command above attaches a python script to breakpoint 1. To remove the breakpoint command:		.. code-tab:: lua

		(lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib
		Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
		(lldb) script -l lua -- counter = 0
		(lldb) breakpoint command add -s lua 1
		Enter your Lua command(s). Type 'quit' to end.
		The commands are compiled as the body of the following Lua function
		function (frame, bp_loc, ...) end
		..> -- Increment our counter
		..> counter = counter + 1
		..> -- Get the name of the function
		..> name = frame:GetFunctionName()
		..> -- Print the order and the function name
		..> print(string.format('[%i] %s', counter, name))
		..> -- Disable the current breakpoint location so it doesn't get hit again
		..> bp_loc:SetEnabled(false)
		..> -- No need to stop here
		..> return false
		..> quit

		The breakpoint command add command above attaches a python script to
		breakpoint 1. To remove the breakpoint command:

::		::

(lldb) breakpoint command delete 1		(lldb) breakpoint command delete 1


Using the python api's to create custom breakpoints		Create custom breakpoints (Python only)
---------------------------------------------------		---------------------------------------


Another use of the Python API's in lldb is to create a custom breakpoint		Another use of the scripting API's in lldb is to create a custom breakpoint
resolver. This facility was added in r342259.		resolver. This facility was added in r342259.

It allows you to provide the algorithm which will be used in the breakpoint's		It allows you to provide the algorithm which will be used in the breakpoint's
search of the space of the code in a given Target to determine where to set the		search of the space of the code in a given Target to determine where to set the
breakpoint locations - the actual places where the breakpoint will trigger. To		breakpoint locations - the actual places where the breakpoint will trigger. To
understand how this works you need to know a little about how lldb handles		understand how this works you need to know a little about how lldb handles
breakpoints.		breakpoints.

▲ Show 20 Lines • Show All 133 Lines • ▼ Show 20 Lines
can pass in an arbitrary SBStructuredData object, so you can create more		can pass in an arbitrary SBStructuredData object, so you can create more
complex parametrizations. SBStructuredData has a handy SetFromJSON method which		complex parametrizations. SBStructuredData has a handy SetFromJSON method which
you can use for this purpose. Your __init__ function gets passed this		you can use for this purpose. Your __init__ function gets passed this
SBStructuredData object. This API also allows you to directly provide the list		SBStructuredData object. This API also allows you to directly provide the list
of Modules and the list of CompileUnits that will make up the SearchFilter. If		of Modules and the list of CompileUnits that will make up the SearchFilter. If
you pass in empty lists, the breakpoint will use the default "search		you pass in empty lists, the breakpoint will use the default "search
everywhere,accept everything" filter.		everywhere,accept everything" filter.

Using the python API' to create custom stepping logic		Create custom stepping logic (Python only)
-----------------------------------------------------		------------------------------------------

A slightly esoteric use of the Python API's is to construct custom stepping		A slightly esoteric use of the Python API's is to construct custom stepping
types. LLDB's stepping is driven by a stack of "thread plans" and a fairly		types. LLDB's stepping is driven by a stack of "thread plans" and a fairly
simple state machine that runs the plans. You can create a Python class that		simple state machine that runs the plans. You can create a Python class that
works as a thread plan, and responds to the requests the state machine makes to		works as a thread plan, and responds to the requests the state machine makes to
run its operations.		run its operations.

There is a longer discussion of scripted thread plans and the state machine,		There is a longer discussion of scripted thread plans and the state machine,
▲ Show 20 Lines • Show All 45 Lines • ▼ Show 20 Lines
in/out/over and run-to-address) in front of itself on the stack, which can be		in/out/over and run-to-address) in front of itself on the stack, which can be
used to compose more complex stepping operations. When you use subsidiary plans		used to compose more complex stepping operations. When you use subsidiary plans
your explains_stop and should_stop methods won't get called until the		your explains_stop and should_stop methods won't get called until the
subsidiary plan is done, or the process stops for an event the subsidiary plan		subsidiary plan is done, or the process stops for an event the subsidiary plan
doesn't explain. For instance, step over plans don't explain a breakpoint hit		doesn't explain. For instance, step over plans don't explain a breakpoint hit
while performing the step-over.		while performing the step-over.


Create a new lldb command using a Python function		Create a new lldb command (Python only)
-------------------------------------------------		---------------------------------------
		tammelaUnsubmitted Not Done Reply Inline Actions So I'm guessing some sections are still missing some updates because the Lua functionality is not there yet right? If so, I would add some note that this is not currently supported in Lua. tammela: So I'm guessing some sections are still missing some updates because the Lua functionality is…

Python functions can be used to create new LLDB command interpreter commands,		Python functions can be used to create new LLDB command interpreter commands,
which will work like all the natively defined lldb commands. This provides a		which will work like all the natively defined lldb commands. This provides a
very flexible and easy way to extend LLDB to meet your debugging requirements.		very flexible and easy way to extend LLDB to meet your debugging requirements.

To write a python function that implements a new LLDB command define the		To write a python function that implements a new LLDB command define the
function to take four arguments as follows:		function to take four arguments as follows:

Show All 23 Lines	::
def command_function(debugger, command, exe_ctx, result, internal_dict):		def command_function(debugger, command, exe_ctx, result, internal_dict):
# Your code goes here		# Your code goes here

+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+		+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
\| Argument \| Type \| Description \|		\| Argument \| Type \| Description \|
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+		+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
\| `debugger` \| `lldb.SBDebugger` \| The current debugger object. \|		\| `debugger` \| `lldb.SBDebugger` \| The current debugger object. \|
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+		+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
\| `command` \| `python string` \| A python string containing all arguments for your command. If you need to chop up the arguments \|		\| `command` \| `string` \| A python string containing all arguments for your command. If you need to chop up the arguments \|
\| \| \| try using the `shlex` module's shlex.split(command) to properly extract the \|		\| \| \| try using the `shlex` module's shlex.split(command) to properly extract the \|
\| \| \| arguments. \|		\| \| \| arguments. \|
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+		+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
\| `exe_ctx` \| `lldb.SBExecutionContext` \| An execution context object carrying around information on the inferior process' context in which the command is expected to act \|		\| `exe_ctx` \| `lldb.SBExecutionContext` \| An execution context object carrying around information on the inferior process' context in which the command is expected to act \|
\| \| \| \|		\| \| \| \|
\| \| \| Optional since lldb 3.5.2, unavailable before \|		\| \| \| Optional since lldb 3.5.2, unavailable before \|
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+		+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
\| `result` \| `lldb.SBCommandReturnObject` \| A return object which encapsulates success/failure information for the command and output text \|		\| `result` \| `lldb.SBCommandReturnObject` \| A return object which encapsulates success/failure information for the command and output text \|
▲ Show 20 Lines • Show All 138 Lines • ▼ Show 20 Lines	::
...		...
>>> ^D		>>> ^D
(lldb) command script add pofoo -f pofoo_funct		(lldb) command script add pofoo -f pofoo_funct
(lldb) pofoo aString		(lldb) pofoo aString
$1 = 0x000000010010aa00 Hello Worldfoobar		$1 = 0x000000010010aa00 Hello Worldfoobar
(lldb) pofoo anotherString		(lldb) pofoo anotherString
$2 = 0x000000010010aba0 Let's Be Friendsfoobar		$2 = 0x000000010010aba0 Let's Be Friendsfoobar

Using the lldb.py module in Python		Using the lldb module in Python and Lua
----------------------------------		---------------------------------------

LLDB has all of its core code build into a shared library which gets used by		LLDB has all of its core code build into a shared library which gets used by
the `lldb` command line application. On macOS this shared library is a		the `lldb` command line application. On macOS this shared library is a
framework: LLDB.framework and on other unix variants the program is a shared		framework: LLDB.framework and on other unix variants the program is a shared
library: lldb.so. LLDB also provides an lldb.py module that contains the		library: lldb.so. LLDB also provides an lldb.py module that contains the
bindings from LLDB into Python. To use the LLDB.framework to create your own		bindings from LLDB into Python. To use the LLDB.framework to create your own
stand-alone python programs, you will need to tell python where to look in		stand-alone python programs, you will need to tell python where to look in
order to find this module. This is done by setting the PYTHONPATH environment		order to find this module. This is done by setting the PYTHONPATH environment
Show All 16 Lines
Alternately, you can append the LLDB Python directory to the sys.path list		Alternately, you can append the LLDB Python directory to the sys.path list
directly in your Python code before importing the lldb module.		directly in your Python code before importing the lldb module.

Now your python scripts are ready to import the lldb module. Below is a python		Now your python scripts are ready to import the lldb module. Below is a python
script that will launch a program from the current working directory called		script that will launch a program from the current working directory called
"a.out", set a breakpoint at "main", and then run and hit the breakpoint, and		"a.out", set a breakpoint at "main", and then run and hit the breakpoint, and
print the process, thread and frame objects if the process stopped:		print the process, thread and frame objects if the process stopped:

::		.. tabs::
		.. code-tab:: python

#!/usr/bin/env python		#!/usr/bin/env python

import lldb		import lldb
import os		import os

def disassemble_instructions(insts):		def disassemble_instructions(insts):
for i in insts:		for i in insts:
print i		print i

# Set the path to the executable to debug		# Set the path to the executable to debug
exe = "./a.out"		exe = "./a.out"

# Create a new debugger instance		# Create a new debugger instance
debugger = lldb.SBDebugger.Create()		debugger = lldb.SBDebugger.Create()

# When we step or continue, don't return from the function until the process		# When we step or continue, don't return from the function until the process
# stops. Otherwise we would have to handle the process events ourselves which, while doable is		# stops. Otherwise we would have to handle the process events ourselves which, while doable is
#a little tricky. We do this by setting the async mode to false.		#a little tricky. We do this by setting the async mode to false.
debugger.SetAsync (False)		debugger.SetAsync (False)

# Create a target from a file and arch		# Create a target from a file and arch
print "Creating a target for '%s'" % exe		print "Creating a target for '%s'" % exe

target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)		target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)

if target:		if target:
# If the target is valid set a breakpoint at main		# If the target is valid set a breakpoint at main
main_bp = target.BreakpointCreateByName ("main", target.GetExecutable().GetFilename());		main_bp = target.BreakpointCreateByName ("main", target.GetExecutable().GetFilename());

print main_bp		print main_bp

# Launch the process. Since we specified synchronous mode, we won't return		# Launch the process. Since we specified synchronous mode, we won't return
# from this function until we hit the breakpoint at main		# from this function until we hit the breakpoint at main
process = target.LaunchSimple (None, None, os.getcwd())		process = target.LaunchSimple (None, None, os.getcwd())

# Make sure the launch went ok		# Make sure the launch went ok
if process:		if process:
# Print some simple process info		# Print some simple process info
state = process.GetState ()		state = process.GetState ()
print process		print process
if state == lldb.eStateStopped:		if state == lldb.eStateStopped:
# Get the first thread		# Get the first thread
thread = process.GetThreadAtIndex (0)		thread = process.GetThreadAtIndex (0)
if thread:		if thread:
# Print some simple thread info		# Print some simple thread info
print thread		print thread
# Get the first frame		# Get the first frame
frame = thread.GetFrameAtIndex (0)		frame = thread.GetFrameAtIndex (0)
if frame:		if frame:
# Print some simple frame info		# Print some simple frame info
print frame		print frame
function = frame.GetFunction()		function = frame.GetFunction()
# See if we have debug info (a function)		# See if we have debug info (a function)
if function:		if function:
# We do have a function, print some info for the function		# We do have a function, print some info for the function
print function		print function
# Now get all instructions for this function and print them		# Now get all instructions for this function and print them
insts = function.GetInstructions(target)		insts = function.GetInstructions(target)
disassemble_instructions (insts)		disassemble_instructions (insts)
else:		else:
# See if we have a symbol in the symbol table for where we stopped		# See if we have a symbol in the symbol table for where we stopped
symbol = frame.GetSymbol();		symbol = frame.GetSymbol();
if symbol:		if symbol:
# We do have a symbol, print some info for the symbol		# We do have a symbol, print some info for the symbol
print symbol		print symbol

Writing lldb frame recognizers in Python		.. code-tab:: lua
----------------------------------------
		local lldb = require('lldb')

		function disassemble_instructions(insts)
		for _, i in ipairs(insts) do
		print(i)
		end
		end

		-- Set the path to the executable to debug
		local exe = './a.out'

		-- Debugger requires initialization before using in Lua
		lldb.SBDebugger.Initialize()
		-- Create a new debugger instance
		local debugger = lldb.SBDebugger.Create()

		-- When we step or continue, don't return from the function until the process
		-- stops. Otherwise we would have to handle the process events ourselves which, while doable is
		-- a little tricky. We do this by setting the async mode to false.
		debugger:SetAsync(false)

		-- Create a target from a file and arch
		print(string.format("Creating a target for '%s'", exe))

		local target = debugger:CreateTargetWithFileAndArch(exe, lldb.LLDB_ARCH_DEFAULT)

		if target then
		-- If the target is valid set a breakpoint at main
		local main_bp = target:BreakpointCreateByName("main", target:GetExecutable():GetFilename());

		print(main_bp)

		-- Launch the process. Since we specified synchronous mode, we won't return
		-- from this function until we hit the breakpoint at main
		local process = target:LaunchSimple(nil, nil, nil)

		-- Make sure the launch went ok
		if process then
		-- Print some simple process info
		local state = process:GetState()
		print(process)
		if state == lldb.eStateStopped then
		-- Get the first thread
		thread = process:GetThreadAtIndex(0)
		if thread then
		-- Print some simple thread info
		print(thread)
		-- Get the first frame
		frame = thread:GetFrameAtIndex(0)
		if frame then
		-- Print some simple frame info
		print(frame)
		func = frame:GetFunction()
		-- See if we have debug info (a function)
		if func:IsValid() then
		-- We do have a function, print some info for the function
		print(func)
		-- Now get all instructions for this function and print them
		local insts = func:GetInstructions(target)
		disassemble_instructions(insts)
		else
		-- See if we have a symbol in the symbol table for where we stopped
		symbol = frame:GetSymbol()
		if symbol then
		-- We do have a symbol, print some info for the symbol
		print(symbol)
		end
		end
		end
		end
		end
		end
		end

		Writing lldb frame recognizers in Python (Python only)
		------------------------------------------------------

Frame recognizers allow for retrieving information about special frames based		Frame recognizers allow for retrieving information about special frames based
on ABI, arguments or other special properties of that frame, even without		on ABI, arguments or other special properties of that frame, even without
source code or debug info. Currently, one use case is to extract function		source code or debug info. Currently, one use case is to extract function
arguments that would otherwise be inaccessible, or augment existing arguments.		arguments that would otherwise be inaccessible, or augment existing arguments.

Adding a custom frame recognizer is done by implementing a Python class and		Adding a custom frame recognizer is done by implementing a Python class and
using the 'frame recognizer add' command. The Python class should have a		using the 'frame recognizer add' command. The Python class should have a
Show All 33 Lines	::
(lldb) b read		(lldb) b read
(lldb) r		(lldb) r
Process 1234 stopped		Process 1234 stopped
* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.3		* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.3
frame #0: 0x00007fff06013ca0 libsystem_kernel.dylib`read		frame #0: 0x00007fff06013ca0 libsystem_kernel.dylib`read
(lldb) frame variable		(lldb) frame variable
(int) fd = 3		(int) fd = 3

Writing Target Stop-Hooks in Python:		Writing Target Stop-Hooks in Python (Python only)
------------------------------------		-------------------------------------------------

Stop hooks fire whenever the process stops just before control is returned to the		Stop hooks fire whenever the process stops just before control is returned to the
user. Stop hooks can either be a set of lldb command-line commands, or can		user. Stop hooks can either be a set of lldb command-line commands, or can
be implemented by a suitably defined Python class. The Python based stop-hooks		be implemented by a suitably defined Python class. The Python based stop-hooks
can also be passed as set of -key -value pairs when they are added, and those		can also be passed as set of -key -value pairs when they are added, and those
will get packaged up into a SBStructuredData Dictionary and passed to the		will get packaged up into a SBStructuredData Dictionary and passed to the
constructor of the Python object managing the stop hook. This allows for		constructor of the Python object managing the stop hook. This allows for
parametrization of the stop hooks.		parametrization of the stop hooks.
Show All 35 Lines

This is an archive of the discontinued LLVM Phabricator instance.

[lldb][docs] Add reference docs for Lua scripting
Needs RevisionPublic

Details

Diff Detail

Event Timeline

Revision Contents

Diff 366494

lldb/docs/conf.py

lldb/docs/index.rst

lldb/docs/use/python-reference.rst

lldb/docs/use/python.rst

lldb/docs/use/scripting-example.rst

lldb/docs/use/scripting-reference.rst

This is an archive of the discontinued LLVM Phabricator instance.

[lldb][docs] Add reference docs for Lua scriptingNeeds RevisionPublic

Details

Diff Detail

Event Timeline

Revision Contents

Diff 366494

lldb/docs/conf.py

lldb/docs/index.rst

lldb/docs/use/python-reference.rst

lldb/docs/use/python.rst

lldb/docs/use/scripting-example.rst

lldb/docs/use/scripting-reference.rst

[lldb][docs] Add reference docs for Lua scripting
Needs RevisionPublic