xpcall
Lua function

xpcall

Summary

Calls a function with a custom error handler

Prototype

ok, result = xpcall (f, err)


Description

Calls function f with err as the custom error handler.

If an error occurs in f it is caught and the error-handler 'err' is called. Then xpcall returns false, and whatever the error handler returned.

If there is no error in f, then xpcall returns true, followed by the function results from f.

Note that the supplied error function is called before the stack is unwound (in case of error) so this is a good time to find what functions were on the stack leading up to the error. In the example below we use the debug.traceback function, which shows a stack trace as at the time of the error.


function f ()
  return "a" + 2  -- will cause error
end -- f

function err (x)
  print ("err called", x)
  return "oh no!"
end -- err

print (xpcall (f, err))

 -->
 
err called [string "Immediate"]:2: attempt to perform arithmetic on a string value
false oh no!

function f2 ()
  return 2 + 2
end -- f

print (xpcall (f, err))  --> true 4

function f ()
return "a" + 2
end -- f

print (xpcall (f, debug.traceback))

 -->

false   stdin:2: attempt to perform arithmetic on a string value
stack traceback:
        stdin:2: in function `f'
        [C]: in function `xpcall'
        stdin:1: in main chunk
        [C]: ?


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_assert assert (Asserts that condition is not nil and not false)
LUA_collectgarbage collectgarbage (Collects garbage)
LUA_dofile dofile (Executes a Lua file)
LUA_error error (Raises an error message)
LUA_gcinfo gcinfo (Returns amount of dynamic memory in use)
LUA_getfenv getfenv (Returns the current environment table)
LUA_getmetatable getmetatable (Returns the metatable for the object)
LUA_ipairs ipairs (Iterates over a numerically keyed table)
LUA_load load (Loads a chunk by calling a function repeatedly)
LUA_loadfile loadfile (Loads a Lua file and parses it)
LUA_loadlib loadlib (Loads a DLL (obsolete in Lua 5.1))
LUA_loadstring loadstring (Compiles a string of Lua code)
LUA_module module (Creates a Lua module)
LUA_next next (Returns next key / value pair in a table)
LUA_pairs pairs (Traverse all items in a table)
LUA_pcall pcall (Calls a function in protected mode)
LUA_print print (Prints its arguments)
LUA_rawequal rawequal (Compares two values for equality without invoking metamethods)
LUA_rawget rawget (Gets the value of a table item without invoking metamethods)
LUA_rawset rawset (Sets the value of a table item without invoking metamethods)
LUA_require require (Loads a module)
LUA_select select (Returns items in a list)
LUA_setfenv setfenv (Sets a function's environment)
LUA_setmetatable setmetatable (Sets the metatable for a table)
LUA_tonumber tonumber (Converts a string (of the given base) to a number)
LUA_tostring tostring (Converts its argument to a string)
LUA_type type (Returns the type of a variable)
LUA_unpack unpack (Unpacks a table into individual items)

(Help topic: lua=xpcall)

DOC_contents Documentation contents page