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 <tom-
    stubby@onegeek.org>. There is a web page for Stubby available at
    http://onegeek.org/~tom/software/stubby/.

SEE ALSO
    stubby-config(1), stubby-auto(1)

