NAME stubby - creates stubs for dynamic link libraries. SYNOPSIS stubby [-o outputfile] [-L libdir] [-T dltype] [inputfile] stubby -h stubby -V DESCRIPTION Stubby is a tool that enables programmers and packagers to add transparent support for optional run-time dynamic linking of shared libraries. This allows for the creation of applications that can gain additional functionality if a library is present, but that does not fail to load if the library is not installed. (Unless a function in that library is called.) Stubby works by creating functions with the same names as the corresponding library functions. The first time one of these stub functions is called, the corresponding library is loaded. If the library cannot be loaded, the abort() function is called to terminate the program. Otherwise, the function is located and called with the same arguments as given to the stub function. The input to stubby is in C-like format. This is a format that allows for declarations of functions and variables in a manner similar to the way that the C language allows them. There's more information in the section named C-LIKE INPUT LANGUAGE below. If an input file is given on the command line, input is read from it. Otherwise, the input is read from standard input. OPTIONS Stubby allows it's behavior to be controlled with command line options. Here's a list: -o filename The `-o' option selects an output file. If no output file is selected, stubby defaults to standard output. -L libdir This selects the library directory. The dltype is appended to the library to find the default location for stub template files. Before stubby looks in that spot, it first looks in the directory specified by the STUBBYPATH environment variable. If that's not set it looks for the stub files in the current directory, and if that fails it looks in the default location. -T dltype This selects the type of stub to used. It's appended to the library directory to find the stub files. -h This option prints out a short usage message. -V This options prints out a message containing version and copyright information. C-LIKE INPUT LANGUAGE Stubby reads in it's input as a series of statements. At first glance, these statements seem to resemble C, but there are some important differences. Please read on for more information about the different statements. As the input is being read in, it's printed directly to the output until a line beginning with '%%' is read. Once a line is read, it's printed to output. This allows various C directives to be placed into the output file. The language is made up of a series of statements. Each statement is followed by a semicolon. The syntax for each type of statement is described below, but first a list of some of the types that can be made arguments of the various statements. NAME This is a short, non-quoted string of characters. It much begin with a letter, and cannot contain whitespace. TYPE This is a NAME that has been declared as a type using the 'type' statement. Once a NAME has been declared as a TYPE, it can no longer be used as a NAME. STRING This is a string enclosed in double quotes. No escape substitution is done on this string. The statements that Stubby supports are: include STRING The include statement commands the inclusion of code from another C-Like language file. Parsing is immediately begun on this file, without waiting for the '%%' delimiter. include "morefuncs.stub"; type NAME Converts the name from a straight name to a type. After this directive, use of the name as a name rather than a type is an error. At the start, no types are declared. Even standard types must be declared using this statement. Pointers should be declared as the base type only. Structs don't need to be declared at all. type int; type ReallyInterestingType; library NAME STRING This declares a library. The string is the name of the library, while the name is a stub that's used to prefix all of the internal functions referencing this library. It must be unique. This statement must be given before any of the statements following this one. Among other things, this declares a function with the name and type: `int PREFIX_lib_check()', where PREFIX is the name given. This function returns true if the library can be loaded, and false otherwise. It's present make it possible prevent aborts in the case of a library not being found, provided the code is willing to check for that case. library stubtest "testlib.so"; library stubgtk "libgtk-1.2.so.0"; load STRING This tells Stubby to generate code to load a second library that the library declared with the previous 'library' directive depends on. (This is for the case in which one shared library depends on another.) load "testdep.so"; load "libgdk-1.2.so.0"; C style declarations of functions and types. This is perhaps the most important part of a Stubby input file. A function that's declared is dynamically loaded the first time it's called. A variable that's declared is synced with the library's copy each time a function in that library is called. One of the biggest differences between Stubby and C is that Stubby doesn't support the [] array notation. Use a pointer '*' instead. void function1(void); int function2(int, struct foo *, int *); char *function3(char *foo, char *bar); void (*)(int, int) function4(void(*)(int, int), int, int); int var1; char *var2; struct smeg *var3; void (*funcvar)(int, int); AUTHOR Both Stubby and this man page were written by Tom Rothamel . There is a web page for Stubby available at http://onegeek.org/~tom/software/stubby/. SEE ALSO stubby-config(1), stubby-auto(1)