This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.
The fourth edition targets Lua 5.3 and is available at Amazon and other bookstores.
By buying the book, you also help to support the Lua project.

## 25.2 – Calling Lua Functions

A great strength of Lua is that a configuration file can define functions to be called by the application. For instance, you can write an application to plot the graph of a function and use Lua to define the functions to be plotted.

The API protocol to call a function is simple: First, you push the function to be called; second, you push the arguments to the call; then you use `lua_pcall` to do the actual call; finally, you pop the results from the stack.

As an example, let us assume that our configuration file has a function like

```    function f (x, y)
return (x^2 * math.sin(y))/(1 - x)
end
```
and you want to evaluate, in C, `z = f(x, y)` for given `x` and `y`. Assuming that you have already opened the Lua library and run the configuration file, you can encapsulate this call in the following C function:
```    /* call a function `f' defined in Lua */
double f (double x, double y) {
double z;

/* push functions and arguments */
lua_getglobal(L, "f");  /* function to be called */
lua_pushnumber(L, x);   /* push 1st argument */
lua_pushnumber(L, y);   /* push 2nd argument */

/* do the call (2 arguments, 1 result) */
if (lua_pcall(L, 2, 1, 0) != 0)
error(L, "error running function `f': %s",
lua_tostring(L, -1));

/* retrieve result */
if (!lua_isnumber(L, -1))
error(L, "function `f' must return a number");
z = lua_tonumber(L, -1);
lua_pop(L, 1);  /* pop returned value */
return z;
}
```

You call `lua_pcall` with the number of arguments you are passing and the number of results you want. The fourth argument indicates an error-handling function; we will discuss it in a moment. As in a Lua assignment, `lua_pcall` adjusts the actual number of results to what you have asked for, pushing nils or discarding extra values as needed. Before pushing the results, `lua_pcall` removes from the stack the function and its arguments. If a function returns multiple results, the first result is pushed first; so, if there are n results, the first one will be at index -n and the last at index -1.

If there is any error while `lua_pcall` is running, `lua_pcall` returns a value different from zero; moreover, it pushes the error message on the stack (but still pops the function and its arguments). Before pushing the message, however, `lua_pcall` calls the error handler function, if there is one. To specify an error handler function, we use the last argument of `lua_pcall`. A zero means no error handler function; that is, the final error message is the original message. Otherwise, that argument should be the index in the stack where the error handler function is located. Notice that, in such cases, the handler must be pushed in the stack before the function to be called and its arguments.

For normal errors, `lua_pcall` returns the error code `LUA_ERRRUN`. Two special kinds of errors deserve different codes, because they never run the error handler. The first kind is a memory allocation error. For such errors, `lua_pcall` always returns `LUA_ERRMEM`. The second kind is an error while Lua is running the error handler itself. In that case it is of little use to call the error handler again, so `lua_pcall` returns immediately with a code `LUA_ERRERR`.