It Seemed Like A Good Idea, At The Time

I’m sorry this post has taken so long.  I started writing it over a week ago, but by the time it was finished, it looked more like a reference document than a guide to basic usage.  I decided that a document like that would be much better if placed on the SoLoad Wiki.

After much editing down, I ended up with this tutorial, which is much easier to read.

The SoLoad Foreign Function Server is a program that allows interpreters and scripting languages to call C functions.  The only requirements for use are those necessary to start a process and communicate with it.

Previously, I explained the need for and the purpose of SoLoad.  In this post, I will explain how it is used in a command-line session.

Starting

SoLoad has, at the time of this writing, two methods of communication with the outside world.  It can talk over the standard input/output streams, and via TCP.  To start SoLoad and control it over stdin, use the command

soload stdin

Similarly, to use it over TCP, just say

soload tcp <port>

Once you have connected to the port via telnet, there should be no further differences between the different communications methods.

Opening a Library

open path [short-form]


To open a library, use the open command.  The open command takes one or two arguments.  The first is the path to the library, and the second is an optional short name for the library.  If provided, this short name can be used interchangeably with the library identifier that is returned by the command.

For the purposes of this example, we will try to open the libm shared library.  I assume that the path to it is “/lib/libm.so.6″ . If it is different on your system, the command will need to be modified accordingly.

So, to open the libm library, the command goes

open /lib/libm.so.6 libm


This opens the library and assigns it a short name of “libm”.

Loading a Function

load library-id function-name return-type num-args arg-types*

Loading a function from a library is done with the load command.  The load command takes as its arguments: a library identifier, the name of the function to be loaded, the return type, the number of arguments to the function, and the types of all the arguments.  For our purposes, the command will look like

load libm sin double 1 double

If, however, we had opted not to provide a short name for the library when opening it, the call would probably look something more like

load 0x125FA427 sin double 1 double

Calling a Function

call function-id arguments*

To call a function, use the call command.  The call command takes a function identifier, and a number of arguments.  For us, it will look like

call sin 0.34612

and will return the result of the call.

Exiting

exit

To exit, simply type exit .  Everything should automatically be unloaded, and SoLoad will close.

Cleanup (Optional)

unload function-id
close library-id

The following functions don’t usually need to be used.  They are provided simply because doing so adds barely any complexity to the program, and allows use in situations where libraries must be continually loaded and unloaded without exiting, and without filling up all available memory with old library references.

Again, SoLoad will automatically do this cleanup when it exits, so you are free to just quit now if you wish.

To unload a function, use the unload command.  It takes a function identifier as its only argument.  It would look like

unload sin

Similarly, to close a library, simply say

close libm

The library is closed, and functions loaded from it are no longer valid. (Note: Closing a library does not automatically unload all of its functions, but those functions will still be unloaded at exit)

A More Complex Example

The following is a transcript of a simple interaction with the SDL library.  SoLoad will be used to open SDL, create a window, and then quit.

> soload stdin
> open /usr/lib/libSDL.so sdl
0x9fd7058
> load sdl SDL_Init int 1 uint32
0x9fd7be8
> load sdl SDL_SetVideoMode pointer 4 int int int uint32
0x9fd7bc8
> load sdl SDL_Quit void 0
0x9fd7d88
> call SDL_Init 0
0
> call SDL_SetVideoMode 640 480 16 0
0xa004998
> call SDL_Quit
@�
> exit
exit

Stay tuned for the next post in the series, in which I will discuss intermediate level usage (structs and strings).