3.16 – Defining C Functions

Lua can be extended with functions written in C. These functions must be of type lua_CFunction, which is defined as

       typedef int (*lua_CFunction) (lua_State *L);

A C function receives a Lua state and returns an integer, the number of values it wants to return to Lua.

In order to communicate properly with Lua, a C function must follow 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, its first argument (if any) is at index 1. 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 discharged by Lua. Like a Lua function, a C function called by Lua can also return many results.

As an example, the following function receives a variable number of numerical arguments and returns their average and sum:

       static int foo (lua_State *L) {
         int n = lua_gettop(L);    /* number of arguments */
         lua_Number sum = 0;
         int i;
         for (i = 1; i <= n; i++) {
           if (!lua_isnumber(L, i)) {
             lua_pushstring(L, "incorrect argument to function `average'");
             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 */
       }

To register a C function to Lua, there is the following convenience macro:

       #define lua_register(L,n,f) \
               (lua_pushstring(L, n), \
                lua_pushcfunction(L, f), \
                lua_settable(L, LUA_GLOBALSINDEX))
     /* lua_State *L;    */
     /* const char *n;   */
     /* lua_CFunction f; */

which receives the name the function will have in Lua and a pointer to the function. Thus, the C function foo above may be registered in Lua as average by calling

       lua_register(L, "average", foo);