Debug facilities

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.

Below is a list of all debug functions.

### debug() {params[anchor=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.

Parameters:

• object — object to get the environment of

type object : table, userdata, thread or function

Returns

the environment of the object

Returns

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

Parameters:

• function — function to get information on

type function : function or number

• what (string) — what information on the function to return

Returns

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.

• level (number) — level of the stack

• local (number) — index of the local variable

Returns

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

Parameters:

• object — object to get the metatable of

type object : table, userdata, thread or function

Returns

a metatable of the object or nil if it does not have a metatable

Returns

the registry table

Parameters:

• func (function) — function to get the upvalue of

• up (number) — index of the function upvalue

Returns

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

Sets the environment of the object to the table.

Parameters:

• object — object to change the environment of

type object : table, userdata, thread or function

• table (table) — table to set the object environment to

Returns

the object

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.

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

• level (number) — level of the stack

• local (number) — index of the local variable

• value — value to assign to the local variable

type value : boolean, number, string or userdata

Returns

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

Sets the metatable of the object to the table.

Parameters:

• object — object to change the metatable of

type object : table, userdata, thread or function

• table (table) — table to set the object metatable to

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

type value : boolean, number, string or userdata

Returns

the name of the upvalue or nil if there is no upvalue with the given index

Parameters:

• level (number) — the level of the call stack which should contain the path (default is 2)

Returns

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()).

Parameters:

• level (number) — the level of the call stack which should contain the path (default is 2)

Returns

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()).

Parameters:

• message (string) — an optional message prepended to the traceback

• level (number) — specifies at which level to start the traceback (default is 1)

Returns

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'])endw()

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

 
/tmp/tmp/example.luastack traceback:    /tmp/example.lua:4: in function 'w'    /tmp/example.lua:7: in main chunk5