`all` results from the
        function are pushed. Lua takes care that the returned values fit into
        the stack space. The function results are pushed onto the stack in
        direct order (the first result is pushed first), so that after the
        call the last result is on the top of the stack.

        Any error inside the called function is propagated upwards (with a
        `longjmp`).

        The following example shows how the host program may do the equivalent
        to this Lua code:
>lua
            a = f("how", t.x, 14)
<
        Here it is in C:
>c
            lua_getfield(L, LUA_GLOBALSINDEX, "f"); // function to be called
            lua_pushstring(L, "how");                        // 1st argument
            lua_getfield(L, LUA_GLOBALSINDEX, "t");   // table to be indexed
            lua_getfield(L, -1, "x");        // push result of t.x (2nd arg)
            lua_remove(L, -2);                  // remove 't' from the stack
            lua_pushinteger(L, 14);                          // 3rd argument
            lua_call(L, 3, 1);     // call 'f' with 3 arguments and 1 result
            lua_setfield(L, LUA_GLOBALSINDEX, "a");        // set global 'a'
<
        Note that the code above is "balanced": at its end, the stack is back
        to its original configuration. This is considered good programming
        practice.

lua_CFunction                                   *lua-cfunction* *lua_CFunction*
>c
    typedef int (*lua_CFunction) (lua_State *L);
<
        Type for C functions.

        In order to communicate properly with Lua, a C function must use the
        following protocol, which defines the way parameters and results are
        passed: a C function receives its arguments from Lua in its stack in
        direct order (the first argument is pushed first). So, when the
        function starts, `lua_gettop(L)` (see |lua_gettop()|) returns the
        number of arguments received by the function. The first argument (if
        any) is at index 1 and its last argument is at index `lua_gettop(L)`.
        To return values to Lua, a C function just pushes them onto the stack,
        in direct order (the first result is pushed first), and returns the
        number of results. Any other value in the stack below the results will
        be properly discarded by Lua. Like a Lua function, a C function called
        by Lua can also return many results.

                                                       *lua-cfunctionexample*
        As an example, the following function receives a variable number of
        numerical arguments and returns their average and sum:
>c
            static int foo (lua_State *L) {
              int n = lua_gettop(L);    /* number of arguments */
              lua_Number sum = 0;
              int i;
              for (i = 1; i &lt;= n; i++) {
                if (!lua_isnumber(L, i)) {
                  lua_pushstring(L, "incorrect argument");
                  lua_error(L);
                }
                sum += lua_tonumber(L, i);
              }
              lua_pushnumber(L, sum/n); /* first result */
              lua_pushnumber(L, sum);   /* second result */
              return 2;                 /* number of results */
            }
<

lua_checkstack                                                *lua_checkstack()*
>c
    int lua_checkstack (lua_State *L, int extra);
<
        Ensures that there are at least `extra` free stack slots in the stack.
        It returns false if it cannot grow the stack to that size. This
        function never shrinks the stack; if the stack is already larger than
        the new size, it is left unchanged.

lua_close                                                          *lua_close()*
>c
    void lua_close (lua_State *L);
<
        Destroys all objects in the given Lua state (calling the corresponding
        garbage-collection metamethods, if any) and frees all dynamic memory
        used by this state. On several platforms,