Debug facilities

Overview

Tarantool users can benefit from built-in debug facilities that are part of:

• Lua (debug library, see details below) and
• LuaJit (debug.* functions).

The debug library provides an interface for debugging Lua programs. All functions in this library reside in the debug table. Those functions that operate on a thread have an optional first parameter that specifies the thread to operate on. The default is always the current thread.

Index

Below is a list of all debug functions.

debug.debug()¶

Enters an interactive mode and runs each string that the user types in. The user can, among other things, inspect global and local variables, change their values and evaluate expressions.

Enter cont to exit this function, so that the caller can continue its execution.

Note

Commands for debug.debug() are not lexically nested within any function and so have no direct access to local variables.

debug.getfenv(object)¶

Parameters:	object – object to get the environment of
Return:	the environment of the object

debug.gethook([thread])¶

Return:	the current hook settings of the thread as three values: the current hook function the current hook mask the current hook count as set by the debug.sethook() function

debug.getinfo([thread, ]function[, what])¶

Parameters:	function – function to get information on what (string) – what information on the function to return
Return:	a table with information about the function

You can pass in a function directly, or you can give a number that specifies a function running at level function of the call stack of the given thread: level 0 is the current function (getinfo() itself), level 1 is the function that called getinfo(), and so on. If function is a number larger than the number of active functions, getinfo() returns nil.

The default for what is to get all information available, except the table of valid lines. If present, the option f adds a field named func with the function itself. If present, the option L adds a field named activelines with the table of valid lines.

debug.getlocal([thread, ]level, local)¶

Parameters:	level (number) – level of the stack local (number) – index of the local variable
Return:	the name and the value of the local variable with the index local of the function at level level of the stack or nil if there is no local variable with the given index; raises an error if level is out of range

Note

You can call debug.getinfo() to check whether the level is valid.

debug.getmetatable(object)¶

Parameters:	object – object to get the metatable of
Return:	a metatable of the object or nil if it does not have a metatable

debug.getregistry()¶

Return:	the registry table

debug.getupvalue(func, up)¶

Parameters:	func (function) – function to get the upvalue of up (number) – index of the function upvalue
Return:	the name and the value of the upvalue with the index up of the function func or nil if there is no upvalue with the given index

debug.setfenv(object, table)¶

Sets the environment of the object to the table.

Parameters:	object – object to change the environment of table (table) – table to set the object environment to
Return:	the object

debug.sethook([thread, ]hook, mask[, count])¶

Sets the given function as a hook. When called without arguments, turns the hook off.

Parameters:

hook (function) – function to set as a hook mask (string) – describes when the hook will be called; may have the following values: c - the hook is called every time Lua calls a function r - the hook is called every time Lua returns from a function l - the hook is called every time Lua enters a new line of code count (number) – describes when the hook will be called; when different from zero, the hook is called after every count instructions.

debug.setlocal([thread, ]level, local, value)¶

Assigns the value value to the local variable with the index local of the function at level level of the stack.

Parameters:	level (number) – level of the stack local (number) – index of the local variable value – value to assign to the local variable
Return:	the name of the local variable or nil if there is no local variable with the given index; raises an error if level is out of range

Note

You can call debug.getinfo() to check whether the level is valid.

debug.setmetatable(object, table)¶

Sets the metatable of the object to the table.

Parameters:	object – object to change the metatable of table (table) – table to set the object metatable to

debug.setupvalue(func, up, value)¶

Assigns the value value to the upvalue with the index up of the function func.

Parameters:	func (function) – function to set the upvalue of up (number) – index of the function upvalue value – value to assign to the function upvalue
Return:	the name of the upvalue or nil if there is no upvalue with the given index

debug.sourcedir([level])¶

Parameters:	level (number) – the level of the call stack which should contain the path (default is 2)
Return:	a string with the relative path to the source file directory

Instead of debug.sourcedir() one can say debug.__dir__ which means the same thing.

Determining the real path to a directory is only possible if the function was defined in a Lua file (this restriction may not apply for loadstring() since Lua will store the entire string in debug info).

If debug.sourcedir() is part of a return argument, then it should be inside parentheses: return (debug.sourcedir()).

debug.sourcefile([level])¶

Parameters:	level (number) – the level of the call stack which should contain the path (default is 2)
Return:	a string with the relative path to the source file

Instead of debug.sourcefile() one can say debug.__file__ which means the same thing.

Determining the real path to a file is only possible if the function was defined in a Lua file (this restriction may not apply to loadstring() since Lua will store the entire string in debug info).

If debug.sourcefile() is part of a return argument, then it should be inside parentheses: return (debug.sourcefile()).

debug.traceback([thread, ][message][, level])¶

Parameters:	message (string) – an optional message prepended to the traceback level (number) – specifies at which level to start the traceback (default is 1)
Return:	a string with a traceback of the call stack

Debug example:

Make a file in the /tmp directory named example.lua, containing:

function w()
  print(debug.sourcedir())
  print(debug.sourcefile())
  print(debug.traceback())
  print(debug.getinfo(1)['currentline'])
end
w()

Execute tarantool /tmp/example.lua. Expect to see this:

/tmp
/tmp/example.lua
stack traceback:
    /tmp/example.lua:4: in function 'w'
    /tmp/example.lua:7: in main chunk
5