[Home] [Downloads] [Search] [Help/forum]



Sets a debug hook function


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


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

Lua functions

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


Lua base functions
Lua bc (big number) functions
Lua bit manipulation functions
Lua coroutine functions
Lua debug functions
Lua io functions
Lua math functions
Lua os functions
Lua package functions
Lua PCRE regular expression functions
Lua script extensions
Lua string functions
Lua syntax
Lua table functions
Lua utilities
Scripting callbacks - plugins

(Help topic: lua=debug.sethook)

Documentation contents page

Search ...

Enter a search string to find matching documentation.

Search for:   

Quick links: MUSHclient. MUSHclient help. Forum shortcuts. Posting templates. Lua modules. Lua documentation.

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.


Written by Nick Gammon - 5K   profile for Nick Gammon on Stack Exchange, a network of free, community-driven Q&A sites   Marriage equality

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( https://gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Hosted at FutureQuest]