Lua Academy · Lesson

Registering C Functions in Lua

Expose C functions to Lua scripts using luaL_register and lua_pushcfunction.

Registering C Functions in Lua is a free Lua Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Lua Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Overview

C functions can be exposed to Lua scripts. They must have the signature int myFunc(lua_State *L). They read arguments from the stack and push return values.

C Function Signature

Every function callable from Lua is a lua_CFunction: it takes a lua_State*, reads arguments, pushes results, and returns the count of results.

// C code
static int l_add(lua_State *L) {
  double a = luaL_checknumber(L, 1);
  double b = luaL_checknumber(L, 2);
  lua_pushnumber(L, a + b);
  return 1;  // one result
}

Registering as a Global

lua_pushcfunction(L, l_add) pushes the C function, then lua_setglobal(L, "add") registers it as a global in Lua.

// C code
lua_pushcfunction(L, l_add);
lua_setglobal(L, "add");
// Now Lua can call: add(3, 4)

luaL_newlib / luaL_register

// C code
static const luaL_Reg mylib[] = {
  {"add", l_add},
  {"mul", l_mul},
  {NULL, NULL}
};
luaL_newlib(L, mylib);
lua_setglobal(L, "mylib");
// Lua: mylib.add(1, 2)

Reading Arguments

luaL_checknumber(L, n), luaL_checkstring(L, n), etc. read and validate arguments, raising a Lua error if the type is wrong.

Returning Multiple Values

Push multiple values and return their count. Lua will assign them as multiple return values.

// C code
static int l_divmod(lua_State *L) {
  int a = luaL_checkinteger(L, 1);
  int b = luaL_checkinteger(L, 2);
  lua_pushinteger(L, a / b);
  lua_pushinteger(L, a % b);
  return 2;  // two results
}

Upvalues for C Closures

C closures capture upvalues at registration time using lua_pushcclosure(L, fn, n). Access upvalues with lua_upvalueindex(n).

Error Reporting from C

Call luaL_error(L, format, ...) to raise a Lua error from a C function. This never returns — it longjmps to the protected call handler.

// C code
if (divisor == 0)
  luaL_error(L, "division by zero at argument %d", 2);

C Module as a .so/.dll

A C module exposes a luaopen_modname function. Lua's require loads the shared library and calls it to initialize the module.

// C code (shared library entry point)
int luaopen_mymod(lua_State *L) {
  luaL_newlib(L, mymod_funcs);
  return 1;
}

Argument Count Checking

Use lua_gettop(L) to check the number of arguments passed. luaL_checkany(L, n) ensures at least n arguments were provided.

LuaJIT FFI Alternative

LuaJIT's FFI lets you call C functions directly from Lua without writing C wrapper code. It is often simpler for pure function calls. The C API is needed for deeper integration.

C Function Question

What must a Lua-callable C function return?

Recap: Registering C Functions

C functions callable from Lua have signature int f(lua_State*). Read args with luaL_check*, push results, return count. Register individually with lua_pushcfunction or in bulk with luaL_newlib.

Frequently asked questions

Is the “Registering C Functions in Lua” lesson free?

Yes — the full text of “Registering C Functions in Lua” is free to read here on the web, and the Lua Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Lua Academy course, upgrade to CoddyKit PRO.

What will I learn in “Registering C Functions in Lua”?

Expose C functions to Lua scripts using luaL_register and lua_pushcfunction. You practise Lua Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Lua Academy?

No prior experience is required. Lua Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Registering C Functions in Lua” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Lua Academy lesson?

Yes. Every Lua Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Lua Academy