errors during the call,
`lua_pcall` behaves exactly like `lua_call`. However, if there is any
error, `lua_pcall` catches it, pushes a single value on the stack (the
error message), and returns an error code. Like `lua_call`,
`lua_pcall` always removes the function and its arguments from the
stack.
If `errfunc` is 0, then the error message returned on the stack is
exactly the original error message. Otherwise, `errfunc` is the stack
index of an `error` `handler function`. (In the current
implementation, this index cannot be a pseudo-index.) In case of
runtime errors, this function will be called with the error message
and its return value will be the message returned on the stack by
`lua_pcall`.
Typically, the error handler function is used to add more debug
information to the error message, such as a stack traceback. Such
information cannot be gathered after the return of `lua_pcall`, since
by then the stack has unwound.
The `lua_pcall` function returns 0 in case of success or one of the
following error codes (defined in `lua.h`):
- `LUA_ERRRUN` a runtime error.
- `LUA_ERRMEM` memory allocation error. For such errors, Lua does
not call the error handler function.
- `LUA_ERRERR` error while running the error handler function.
lua_pop *lua_pop()*
>c
void lua_pop (lua_State *L, int n);
<
Pops `n` elements from the stack.
lua_pushboolean *lua_pushboolean()*
>c
void lua_pushboolean (lua_State *L, int b);
<
Pushes a boolean value with value `b` onto the stack.
lua_pushcclosure *lua_pushcclosure()*
>c
void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
<
Pushes a new C closure onto the stack.
When a C function is created, it is possible to associate some values
with it, thus creating a C closure (see |lua-cclosure|); these
values are then accessible to the function whenever it is called. To
associate values with a C function, first these values should be
pushed onto the stack (when there are multiple values, the first value
is pushed first). Then `lua_pushcclosure` is called to create and push
the C function onto the stack, with the argument `n` telling how many
values should be associated with the function. `lua_pushcclosure` also
pops these values from the stack.
lua_pushcfunction *lua_pushcfunction()*
>c
void lua_pushcfunction (lua_State *L, lua_CFunction f);
<
Pushes a C function onto the stack. This function receives a pointer
to a C function and pushes onto the stack a Lua value of type
`function` that, when called, invokes the corresponding C function.
Any function to be registered in Lua must follow the correct protocol
to receive its parameters and return its results (see
|lua_CFunction|).
`lua_pushcfunction` is defined as a macro:
>c
#define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
<
lua_pushfstring *lua_pushfstring()*
>c
const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
<
Pushes onto the stack a formatted string and returns a pointer to this
string. It is similar to the C function `sprintf`, but has some
important differences:
- You do not have to allocate space for the result: the result is a
Lua string and Lua takes care of memory allocation (and
deallocation, through garbage collection).
- The conversion specifiers are quite restricted. There are no flags,
widths, or precisions. The conversion specifiers