It Seemed Like a Good Idea at the Time Coding, Mostly

The SoLoad Foreign Function Server (Part II) – Basic Usage

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

Similarly, to use it over TCP, just say

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

Opening a Library

To open a library, use the

command.  The

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

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

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

Loading a Function

Loading a function from a library is done with the

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

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

Calling a Function

To call a function, use the

command takes a function identifier, and a number of arguments.  For us, it will look like

and will return the result of the call.

Exiting

To exit, simply type

.  Everything should automatically be unloaded, and SoLoad will close.

Cleanup (Optional)

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

command.  It takes a function identifier as its only argument.  It would look like

Similarly, to close a library, simply say

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).