Stagegol

wiki

• Lua Example Code
• Lua Programming Example
• C++ With Lua
• Call Lua From C Examples

Step 1: Writing a C function that Lua can call. C/C functions that are called from lua need to take as an input parameter the lua state. The parameters can be examined on the call stack using the functions luatointeger, luatonumber, etc (described above). The first parameter is at index 1, the second parameter is at index 2, and so on. Example A - Execution without pcall. Function square(a) return a. 'a' -This will stop the execution of the code and throws an error, because of the attempt to perform arithmetic on a string value end square(10); print ('Hello World') - This is not being executed because the script was interrupted due to the error. There's an excellent example of Lua-C integration here and here. If you just need to export a function into the global namespace, then: Declare the function (let's call it f) with signature luaCFunction. Call luaregister (L, 'myfunc', f), with L being the Lua state, and function = f.

This is a simple introductory example of how to interface to Lua from C. The C program loads a Lua script file, sets some Lua variables, runs the Lua script, and reads back the return value. The below example works with Lua 5.3.

First, create the below Lua script file and save it as 'script.lua'. This script will dump to the screen the contents of a table named 'foo' (that will be created from the C program) and return the sum of this table's components.

In order to access it from C, we could hack a little program that would construct the table, pass it to the script, and get the returned value. Create a C program called 'test.c' as follows:

It's now time to compile it. Keep in mind you'll need to link against -llua (Lua) possibly -lm (the math library). In the system I wrote this simple test, 'cc -o test test.c -I/usr/local/include -L/usr/local/lib -llua -lm' generated the binary as expected. On another system (OpenSuse? 11.4, gcc4.7) -ldl was also needed to resolve undefined references to 'dlopen' etc.

Finally, running the test you should get something like:

That should demonstrate how the basic API works and how values are passed between C and Lua.

For more, see [Lua API Demo]. It is a module designed for the Lua interpreter that allows you to set up a fake Lua state with a stack, call Lua API functions, and observe their effect on the stack.

RecentChanges · preferences
edit · history
Last edited March 2, 2018 6:09 am GMT (diff)

Troubleshooters.Comand Code Corner Present

From a running Cprogram, you can call a Lua script. The C program can pass arguments tothe Lua script, and the Lua script can pass back a return. The Luascript can serve to initialize the C program, or the Lua script caninstall a callback routine in the C program.
Calling a Lua script from a C program can be daunting without the rightinformation. Different computers have different names and locations forlibraries and include files, and it's difficult to figure out what'scausing compile/link problems.
Further complicating things is that with every major version of Lua,the method of calling Lua from C changes. Much documentation on theInternet is specific to Lua 5.0, and won't work on 5.1. Likewise, thisdocumentation is specific to 5.1, and when 5.2 comes out (it's alpharight now), the documentation on this page won't work on the newversion.
The purpose of this document is to make it easy for you to do simple Lua calls from C programs.
A typical interaction from a C program to a Lua 5.1 script looks something like this:

• Create a Lua state variable
• Load Lua libraries
• Load but don't run the Lua script file
• Priming script run to create script's global vars
  
• Pass all arguments to the Lua script on the stack
• Run the loaded Lua script
• Retrieve the return from the Lua script
  
• Close the Lua state variable

Create a Lua state variable		lua_State *L; L = luaL_newstate();
Load Lua libraries		luaL_openlibs(L);
Load but don't run the Lua script file		luaL_loadfile(L, 'script.lua')
Priming run of the loaded Lua script to create the script's global variables
Pass all arguments to the Lua script on the stack		Various routines, too many to name.
Run the loaded Lua script
Retrieve the return from the Lua script		Various pops and stack calls
Close the Lua state variable		lua_close(L);

Header Files

Always put these three header files at the top of any C program calling Lua:

Compiling and Linking

Nothing is tougher than compiling and linking your first C to Luaprogram. There are way too many variables, it seems like everything's ablack box, and you run around changing things trial and error, crossingyour fingers.
But there's a method to the madness, and this subsection explains it.If you know all the content of this section, try not to be offended orinsulted -- the extra info is for those who don't know it yet.
Here's a typical command to compile it:
Let's break that down:

	Your systems C compilation command. Could be cc, or gcc, or something else.
	Show all warnings. You might choose not to insert this until all other errors and warnings have been fixed.
	The name of the finished executable.
	The name of the C file to compile.
	Every C compiler checks for include files in certain places. But often lua.h, liblua.h and lauxlua.h aren't in those places, so you need to tell the compiler where to find them.
	Every C compiler checks for libraries to link in certainplaces. But often the Lua libraries are elsewhere, so you need to tellthe compiler where to find them.
	Link in the Lua library. The way you name this library in the compiler's -l option requires some thought and research, which will be explained later in this subsection.
	Link in the math library (often not necessary)

The Process of Finding the Right Compile Command

Finding the right compile command is a process that looks something like this:

1. Try to compile, no link, no -Wall, no -I. You might get lucky.
   
2. Find the location of the Lua include files.
3. Using that location, compile, no link, no -Wall.
4. Compile, no link, use -Wall.
5. Find the location and filenames of the Lua library files.
6. Using the location and filenames, compile and link.
7. Test the Executable.
   

Step 1: Try to compile, no link, no -Wall, no -I

Do this:
Notice that the -c means 'compile only, do not link'. Sometimes it'snot all that clear whether an error or warning comes from compile orlink, but it's very clear if you only compile. If the preceding commanddoesn't error out, skip to step 4. However, in my case it errored out:
On to step 2...

Step 2: Find the location of the Lua include files

The three Ubiquitous Lua include files are lua.h, lauxlib.h, and lualib.h. Use your Linux box's locate command to find lua.h after running updatedb to make sure that locate finds everything. Make sure that the directory with lua.h also contains lauxlib.h, and lualib.h.
Obviously the directory you want is /usr/include/lua5.1. Now see if that directory contains the other two:
OK, that's it. You know you need to add -I /usr/include/lua5.1 to the command.

Step 3: Using that location, compile, no link, no -Wall

In my case the preceding worked:
If it hadn't worked, and you'd included all three header files in hello.c, and you're sure you got the additional include directory right, suspect wrong code in hello.c itself. If it doesn't produce errors or warnings, go on to the next step...

Step 4: Compile, no link, use -Wall

In my case, the preceding produced no errors or warnings:
If it produces warnings, try your best to fix them. Warnings are oftena sign of problems that rear their ugly head a week after deployment.
Once you have no errors or warnings, go on to the next step...

Step 5: Find the location and filenames of the Lua library files

First a word about how the -l compiler option works. The -loption assumes every library file starts with 'lib'. Therefore, insteadof making you type -lliblua, it makes you type -llua and then out ofthe goodness of its heart prepends lib before the lua. For instance, if you put -llua, that means that it searches for a file called liblua.a or liblua.o or liblua.so, etc. So you need to find the liblua.* files. Do it as follows:
Here's the partial result:
See the ones called liblua5.1.*? Those are the Lua libraries on my computer. So we have a pretty good idea that the -l argument should be lua5.1.We also know that they're located in /usr/lib, which probably isalready on the C compiler's library path, so we probably don't need a -L compiler option. If these files had been in /usr/lib/lua, we'd have needed an -L option.

Step 6: Using the location and filenames, compile and link

This step differs from step 4 in two ways:

1. We remove the -c so that it will attempt to link
2. We add -llua5.1
   

Here we go...
It worked. If it hadn't, we'd have been forced to troubleshoot.

Step 7: Test the Executable

So let's run it:
You haven't seen the code for hello.c and helloscript.lua yet, but take it from me that the preceding output was exactly what it was supposed to do.

Summary

Here's how you build a C program that runs a Lua script:

Create a Lua state variable		lua_State *L; L = luaL_newstate();
Load Lua libraries		luaL_openlibs(L);
Load but don't run the Lua script file		luaL_loadfile(L, 'script.lua')
Priming run of the loaded Lua script to create the script's global variables
Pass all arguments to the Lua script on the stack		Various routines, too many to name.
Run the loaded Lua script
Retrieve the return from the Lua script		Various pops and stack calls
Close the Lua state variable		lua_close(L);

You always include lua.h, lauxlib.h and lualib.h. You use the Linux locate command to find where those files are, and use that location in a -I compiler option. You always link with liblua, and you use locate commands to find where that library is, and use it in the -l compiler option and if its location isn't in a normal library directory, put its directory in a -L

Lua Example Code

compiler option.
Getting Lua-calling C programs to compile and link can be difficult andfrustrating. To limit the difficulty and frustration, use this process:

1. Try to compile, no link, no -Wall, no -I. You might get lucky.
   
2. Find the location of the Lua include files.
3. Using that location, compile, no link, no -Wall.
4. Compile, no link, use -Wall.
5. Find the location and filenames of the Lua library files.
6. Using the location and filenames, compile and link.
7. Test the Executable.

Now it's time for your Hello World program.
Let's start with the one line Lua script itself. Call it helloscript.lua:
That's it, one line. Notice it doesn't have the #!/usr/bin/lua line on top. It doesn't have to because the C Lua interface has a built-in Lua interpreter which the lua_pcall() function invokes automatically.
So if you run the C program and see the text 'This is coming from lua.' you know you've succeded.
Next let's review the steps covered in the Anatomy of a Lua Call article:

Create a Lua state variable		lua_State *L; L = luaL_newstate();
Load Lua libraries		luaL_openlibs(L);
Load but don't run the Lua script file		luaL_loadfile(L, 'script.lua')
Priming run of the loaded Lua script to create the script's global variables
Pass all arguments to the Lua script on the stack		Various routines, too many to name.
Run the loaded Lua script
Retrieve the return from the Lua script		Various pops and stack calls
Close the Lua state variable		lua_close(L);

Your Hello World program will implement all the above, in that same order, EXCEPT:

• Priming run of the loaded Lua script
• Passing arguments to the Lua script
• Retrieving the return from the Lua script
  

Also, we'll put in an error handler function called bail() just to make the code look more concise. We'll call this program hello.c. Here's the code:
As you can see, it's pretty much the same as discussed in the list ofsteps, except no args are passed into Lua and no return variables arepassed out.
Remembering the discussion from the Anatomy of a Lua Call article, compile and link it, troubleshooting as necessary. Here's how it compiles and links on my computer:
Do what's needed til it compiles no errors, no warnings, with the -Wall compiler option. Then run it. It should look like this:
Study the program. Everything should be pretty obvious except lua_pcall(),and that will be discussed later. Once you've gotten output like thepreceding and really understand what's going on (with the possibleexception of lua_pcall() details), it's time to continue...
Remember the program from the Hello World article did everything except these:

• Priming run of the loaded Lua script
• Passing arguments to the Lua script
• Retrieving the return from the Lua script

In this article we'll do all these things. By the time you're doneconstructing the code in this article, you'll have passedarguments, from Lua to a C subroutine, and have received backreturn values.

Tourist Trap Alert All over the Internet, including on some of the Lua project's owndocumentation, you'll see hints basically telling you that to call a Csubroutine you do: lua_getglobals(L, 'subroutine_name') push_args_to_subroutine if(lua_pcall(L, num_of_args, num_of_returns, 0) error_routine(); These Internet instructions say nothing about doing a priming lua_pcall(), and if you do not do a priming lua_pcall(), you'll get an error message something like this: attempt to call a nil value If you get the preceding error message and don't know it's caused by lack of a priming lua_pcall() (or priming lua_call() or priming dofile()),you're about to have several hours or maybe even days of frustration.Mailing list threads old and new about this error basically tell youRTFM or RTFW, but of course we locals know it was reading the web thatgot you into this problem in the first place. I saw one guy who took the opportunity to tell the asker 'I'm trying tohelp you help yourself but you won't take the help, so now I'm puttingyou on my list of people I won't help.' All for what we locals know wasprobably a simple lack of a priming run THAT SEEMS NOT TO BE DOCUMENTEDANYWHERE! Before calling a function in a Lua script, do that priming run first!!!!!!

OK, let's start by calling a specific function in a Lua script. Create this callfuncscript.lua file:
Now, noting that most of it is from the Hello World article you've already read, create the following callfunc.c:
The only change over the Hello World code is a priming run and pushing the tellme() Lua function via the lua_getglobal() call. Note that the second lua_pcall() still has its second arg, number_of_args, of 0, because you're not sending an argument to the Lua function tellme().

Arguments and Return Value

The previous part of this article was written primarily to make sure you knew that to call a specific Lua function, you need to push that function on the stack with lua_getglobal(), and that you make sure

Lua Programming Example

to do a priming run, because without it you're in for hours of frustrating debugging and detour ridden RTFW.

There are several pieces of example code on the net showing the passingof arguments to entire Lua scripts rather than functions, and thosewhole Lua scripts returning arguments. They do this by, within C,setting a global variable to be used in Lua. I've chosen not toreproduce these techniques here because: In my opinion the internals of such code is a little hard to understand I never liked global variables in the first place. Multiple args to the main Lua script require multiple global variables such code becomes quite muddled Functions are built from the ground up to accept a series of arguments.

Now take your callfuncscript.lua file and add a function called square, so the whole script looks like this:

C++ With Lua

And change callfunc.c to look like the following:
Be sure to notice the following things in the preceding C code:

Call Lua From C Examples

• Even though two functions are called, only one priming run isneeded. Each Lua script requires only one priming run in order tocreate its globals so its functions are visible to the C program.
• In order to fully pass an integer into callfuncscript.lua'ssquare() function and receive the function's return, the lua_pcall()'snargs argument must be 1 (one argument passed in) and its nreturnsargument must be 1 (1 argument passed back). If nargs is 0 you'll getthe dreaded ' attempt to call a number value' error, while if nreturnsis 0 it will always return 0. So remember, this lua_pcall() is lua_pcall(L, 1, 1, 0).

A use case that happens often is the passing of tables to and from Luafunctions. How is that handled? There are a few idioms you see over andover again to make it happen. Before discussing the idioms, here's thecode:

The Lua Program

Here's the Lua program. As you can see, function tweaktable receives atable argument, converts all values to upper case, counts the values,and puts all that info in a new table that's returned.

The C Program

The C program is the same as all the others except stacking argumentsto Lua is a little different, and recovering the table passed back fromLua is a little different. The Lua tweaktable() function takes a tableas its one and only argument and passes back one table. It passes backa completely different table so there's absolutely no question of thechanges being made by reference to the args rather than passback.
Start by looking and running the code, and then we'll discuss some of the idioms that make it work...
The preceding code yields the following output:

Table Argument Passing Idioms

You start by placing an empty table on the stack, and build it it onekey/value pair at a time. The way you place an empty table on the stackis with the following command:
The way you give the now stacked table a key/value pair is like this:
You can do that over and over again with different key/value pairs. Each time the numeric argument to lua_settable() is -3 because lua_settablepops the two stack items above it after incorporating them in itstable, so at its end it's at the same level that it was before youstacked the key and value.
Note that you might be stacking things other than literals. Here are the many pushers available:

lua_pushboolean lua_pushcclosure lua_pushcfunction lua_pushfstring lua_pushinteger

lua_pushlightuserdata lua_pushliteral lua_pushlstring lua_pushnil lua_pushnumber

lua_pushstring lua_pushthread lua_pushvalue lua_pushvfstring

Other functions push or at least put things on the stack, including:

In spite of what it sounds like, this function actually puts the function corresponding to the fcnname argument on the top of the stack.

This function puts an empty table at the top of the stack.

Thisfunction replaces the previous key with the new one, and then pushesthe new value on top of that. You need to do a pop to stay even.

And here are some poppers:

This pops off the stack, number levels.

This pops twice after assigning the key/value pair in the top two stack positions to the table at level -level.

Table Return Passing Idioms

When a Lua function called from C returns ends it puts its returnvalues on the stack. When a return value is a table, retrieving thetable's elements isn't obvious. Assuming the Lua function returned onlyone thing and that thing is a table, then that table is at the stack'stop when it comes back to C. Here's how you access it:
In the preceding, you push a nil in order to make sure lua_next()starts with the first item. The reason you use -2 as an arg tolua_next() is because after you push the nil, the returned table is thesecond item down on the stack. On each iteration, lua_next() replacesthe existing key with the next one, and then pushes the next value ontop of it. Therefore to keep things in place you need one pop per cycle.
On every iteration immediately after lua_next(), the top of the stack is the new value, one down from that is the new key, and one down from that is the table.

[ Troubleshooters.com | Code Corner | Email Steve Litt]

Copyright(C) 2011 by Steve Litt -- Legal