debug.sethook
Lua function

debug.sethook

Summary

Sets a debug hook function

Prototype

debug.sethook (thread, f, mask, count)


Description

Sets the function f as a hook to be called when the "mask" condition is satisfied.

If count is non-zero, it is called after every "count" instructions.

The thread argument is optional and defaults to the current thread.

If called without arguments, turns off the hook.

Mask can be one or more of:


  • c - called every time Lua calls a function
  • r - called every time Lua returns from a function
  • l - called every time Lua enters a new line of code


The mask can be the empty string if you simply want to hook after "count" instructions.

The function f is called with its first parameter being a string, which can be one of:


  • call
  • return
  • tail return
  • line
  • count


In the case of "line" events it gets a second parameter, being the new line number.

Inside the hook you can use debug.getinfo with level 2 to find information about the running function. (Level 0 is getinfo, and level 1 is the hook function). In the case of "tail return" however debug.getinfo will not return valid information.

Here is an example of setting a hook to stop a runaway function from executing for too long:


function test ()
  a = 0
  for i = 0, 1000 do
    a = a + i
  end -- for
end -- test

function hook (why)
  error ("hook reached: " .. why)
end -- hook

debug.sethook (hook, "", 100)

test () --> error:  hook reached: count


In this case, the hook stopped execution after 100 instructions.

This second example uses a "call" hook to display when each new function is entered:


function f ()
  function g ()
  end -- g

 g () 
 g ()
end -- f

function hook (why)
  print ("hook reached: ", why)
  print ("function =", debug.getinfo (2, "n").name)
end -- hook

debug.sethook (hook, "c", 0)

f ()

 -->
 
hook reached:  call
function = f
hook reached:  call
function = g
hook reached:  call
function = g


See Also ...

Topics

DOC_lua_base Lua base functions
DOC_lua_bc Lua bc (big number) functions
DOC_lua_bit Lua bit manipulation functions
DOC_lua_coroutines Lua coroutine functions
DOC_lua_debug Lua debug functions
DOC_lua_io Lua io functions
DOC_lua_math Lua math functions
DOC_lua_os Lua os functions
DOC_lua_package Lua package functions
DOC_lua_rex Lua PCRE regular expression functions
DOC_lua Lua script extensions
DOC_lua_string Lua string functions
DOC_lua_tables Lua table functions
DOC_lua_utils Lua utilities
DOC_scripting Scripting

Lua functions

LUA_debug.debug debug.debug (Enters interactive debugging)
LUA_debug.getfenv debug.getfenv (Returns the environment of an object)
LUA_debug.gethook debug.gethook (Returns the current hook settings)
LUA_debug.getinfo debug.getinfo (Returns a table with information about a function)
LUA_debug.getlocal debug.getlocal (Returns name and value of a local variable)
LUA_debug.getmetatable debug.getmetatable (Returns the metatable of the given object)
LUA_debug.getregistry debug.getregistry (Returns the registry table)
LUA_debug.getupvalue debug.getupvalue (Returns the name and value of an upvalue)
LUA_debug.setfenv debug.setfenv (Sets the environment of an object)
LUA_debug.setlocal debug.setlocal (Sets the value of the local variable)
LUA_debug.setmetatable debug.setmetatable (Sets the metatable for an object)
LUA_debug.setupvalue debug.setupvalue (Sets an upvalue for a function)
LUA_debug.traceback debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.sethook)

DOC_contents Documentation contents page