delve/Documentation/cli/starlark.md

Introduction

Passing a file with the .star extension to the source command will cause delve to interpret it as a starlark script.

Starlark is a dialect of python, a specification of its syntax can be found here.

In addition to the normal starlark built-ins delve defines a number of global functions that can be used to interact with the debugger.

After the file has been evaluated delve will bind any function starting with command_ to a command-line command: for example command_goroutines_wait_reason will be bound to goroutines_wait_reason.

Then if a function named main exists it will be executed.

Global functions with a name that begins with a capital letter will be available to other scripts.

Starlark built-ins

Function	API Call
amend_breakpoint(Breakpoint)	Equivalent to API call AmendBreakpoint
ancestors(GoroutineID, NumAncestors, Depth)	Equivalent to API call Ancestors
attached_to_existing_process()	Equivalent to API call AttachedToExistingProcess
cancel_next()	Equivalent to API call CancelNext
checkpoint(Where)	Equivalent to API call Checkpoint
clear_breakpoint(Id, Name)	Equivalent to API call ClearBreakpoint
clear_checkpoint(ID)	Equivalent to API call ClearCheckpoint
raw_command(Name, ThreadID, GoroutineID, ReturnInfoLoadConfig, Expr, UnsafeCall)	Equivalent to API call Command
create_breakpoint(Breakpoint)	Equivalent to API call CreateBreakpoint
detach(Kill)	Equivalent to API call Detach
disassemble(Scope, StartPC, EndPC, Flavour)	Equivalent to API call Disassemble
eval(Scope, Expr, Cfg)	Equivalent to API call Eval
find_location(Scope, Loc)	Equivalent to API call FindLocation
function_return_locations(FnName)	Equivalent to API call FunctionReturnLocations
get_breakpoint(Id, Name)	Equivalent to API call GetBreakpoint
get_thread(Id)	Equivalent to API call GetThread
is_multiclient()	Equivalent to API call IsMulticlient
last_modified()	Equivalent to API call LastModified
breakpoints()	Equivalent to API call ListBreakpoints
checkpoints()	Equivalent to API call ListCheckpoints
dynamic_libraries()	Equivalent to API call ListDynamicLibraries
function_args(Scope, Cfg)	Equivalent to API call ListFunctionArgs
functions(Filter)	Equivalent to API call ListFunctions
goroutines(Start, Count)	Equivalent to API call ListGoroutines
local_vars(Scope, Cfg)	Equivalent to API call ListLocalVars
package_vars(Filter, Cfg)	Equivalent to API call ListPackageVars
registers(ThreadID, IncludeFp)	Equivalent to API call ListRegisters
sources(Filter)	Equivalent to API call ListSources
threads()	Equivalent to API call ListThreads
types(Filter)	Equivalent to API call ListTypes
process_pid()	Equivalent to API call ProcessPid
recorded()	Equivalent to API call Recorded
restart(Position, ResetArgs, NewArgs)	Equivalent to API call Restart
set_expr(Scope, Symbol, Value)	Equivalent to API call Set
stacktrace(Id, Depth, Full, Defers, Cfg)	Equivalent to API call Stacktrace
state(NonBlocking)	Equivalent to API call State
dlv_command(command)	Executes the specified command as if typed at the dlv_prompt
read_file(path)	Reads the file as a string
write_file(path, contents)	Writes string to a file
cur_scope()	Returns the current evaluation scope
default_load_config()	Returns the current default load configuration

Should I use raw_command or dlv_command?

There are two ways to resume the execution of the target program:

raw_command("continue")
dlv_command("continue")

The first one maps to the API call Command. As such all the caveats explained in the Client HowTo.

The latter is equivalent to typing continue to the (dlv) command line and should do what you expect.

In general dlv_command("continue") should be preferred, unless the behavior you wish to produces diverges significantly from that of the command line's continue.

Creating new commands

Any global function with a name starting with command_ will be made available as a command line command. If the function has a single argument named args all arguments passed on the command line will be passed to the function as a single string.

Otherwise arguments passed on the command line are interpreted as starlark expressions. See the expression arguments example.

If the command function has a doc string it will be used as a help message.

Working with variables

Variables of the target program can be accessed using local_vars, function_args or the eval functions. Each variable will be returned as a Variable struct, with one special field: Value.

Variable.Value

The Value field will return the value of the target variable converted to a starlark value:

• integers, floating point numbers and strings are represented by equivalent starlark values
• structs are represented as starlark dictionaries
• slices and arrays are represented by starlark lists
• maps are represented by starlark dicts
• pointers and interfaces are represented by a one-element starlark list containing the value they point to

For example, given this variable in the target program:

type astruct struct {
	A int
	B int
}

s2 := []astruct{{1, 2}, {3, 4}, {5, 6}, {7, 8}, {9, 10}, {11, 12}, {13, 14}, {15, 16}}

The following is possible:

>>> s2 = eval(None, "s2").Variable
>>> s2.Value[0]                                     # access of a slice item by index
main.astruct {A: 1, B: 2}
>>> a = s2.Value[1]
>>> a.Value.A                                       # access to a struct field
3
>>> a.Value.A + 10                            # arithmetic on the value of s2[1].X
13
>>> a.Value["B"]                                    # access to a struct field, using dictionary syntax
4

For more examples see the linked list example below.

Examples

Listing goroutines and making custom commands

Create a goroutine_start_line command that prints the starting line of each goroutine, sets gsl as an alias:

def command_goroutine_start_line(args):
	gs = goroutines().Goroutines
	for g in gs:
		line = read_file(g.StartLoc.File).splitlines()[g.StartLoc.Line-1].strip()
		print(g.ID, "\t", g.StartLoc.File + ":" + str(g.StartLoc.Line), "\t", line)

def main():
	dlv_command("config alias goroutine_start_line gsl")

Use it like this:

(dlv) source goroutine_start_line.start
(dlv) goroutine_start_line
1 	 /usr/local/go/src/runtime/proc.go:110 	 func main() {
2 	 /usr/local/go/src/runtime/proc.go:242 	 func forcegchelper() {
17 	 /usr/local/go/src/runtime/mgcsweep.go:64 	 func bgsweep(c chan int) {
18 	 /usr/local/go/src/runtime/mfinal.go:161 	 func runfinq() {
(dlv) gsl
1 	 /usr/local/go/src/runtime/proc.go:110 	 func main() {
2 	 /usr/local/go/src/runtime/proc.go:242 	 func forcegchelper() {
17 	 /usr/local/go/src/runtime/mgcsweep.go:64 	 func bgsweep(c chan int) {
18 	 /usr/local/go/src/runtime/mfinal.go:161 	 func runfinq() {

Expression arguments

After evaluating this script:

def command_echo(args):
	print(args)

def command_echo_expr(a, b, c):
	print("a", a, "b", b, "c", c)

The first commnad, echo, takes its arguments as a single string, while for echo_expr it will be possible to pass starlark expression as arguments:

(dlv) echo 2+2, 2-1, 2*3
"2+2, 2-1, 2*3"
(dlv) echo_expr 2+2, 2-1, 2*3
a 4 b 1 c 6

Creating breakpoints

Set a breakpoint on all private methods of package main:

def main():
	for f in functions().Funcs:
		v = f.split('.')
		if len(v) != 2:
			continue
		if v[0] != "main":
			continue
		if v[1][0] >= 'a' and v[1][0] <= 'z':
			create_breakpoint({ "FunctionName": f, "Line": -1 }) # see documentation of RPCServer.CreateBreakpoint

Switching goroutines

Create a command, switch_to_main_goroutine, that searches for a goroutine running a function in the main package and switches to it:

def command_switch_to_main_goroutine(args):
	for g in goroutines().Goroutines:
		if g.currentLoc.function != None and g.currentLoc.function.name.startswith("main."):
			print("switching to:", g.id)
			raw_command("switchGoroutine", GoroutineID=g.id)
			break

Repeatedly executing the target until a breakpoint is hit.

Repeatedly call continue and restart until the target hits a breakpoint.

def command_flaky(args):
	"Repeatedly runs program until a breakpoint is hit"
	while True:
		if dlv_command("continue") == None:
			break
		dlv_command("restart")

Print all elements of a linked list

def command_linked_list(args):
	"""Prints the contents of a linked list.
	
	linked_list <var_name> <next_field_name> <max_depth>

Prints up to max_depth elements of the linked list variable 'var_name' using 'next_field_name' as the name of the link field.
"""
	var_name, next_field_name, max_depth = args.split(" ")
	max_depth = int(max_depth)
	next_name = var_name
	v = eval(None, var_name).Variable.Value
	for i in range(0, max_depth):
		print(str(i)+":",v)
		if v[0] == None:
			break
		v = v[next_field_name]

Find an array element matching a predicate

def command_find_array(arr, pred):
	"""Calls pred for each element of the array or slice 'arr' returns the index of the first element for which pred returns true.
	
	find_arr <arr> <pred>
	
Example use (find the first element of slice 's2' with field A equal to 5):
	
	find_arr "s2", lambda x: x.A == 5
"""
	arrv = eval(None, arr).Variable
	for i in range(0, arrv.Len):
		v = arrv.Value[i]
		if pred(v):
			print("found", i)
			return

	print("not found")