dld(3)

NAME
dld_init, dld_link, dld_get_symbol, dld_get_func, dld_unlink_by_file, dld_unlink_by_symbol, dld_function_executable_p - dynamic link editor and loader

SYNTAX
#include <dld.h>

dld_init (path)
char *path;

dld_link (path)
char *path;

unsigned long dld_get_symbol (id)
char *id;

unsigned long dld_get_func (func)
char *func;

dld_unlink_by_file (path, force);
char *path;
int force;

dld_unlink_by_symbol (id, force)
char *id;
int force;

dld_function_executable_p (func)
char *func;

DESCRIPTION
This package allows an executing process to dynamically link and load relocatable object files into the process' address space. The newly loaded functions can then be called in a way similar to calling ordinary functions. All external references are resolved in the same way as the conventional link editor (ld(1)). Libraries are searched in the usual way and only the required modules will be loaded. The dynamically linked-in modules can later be unlinked. Memory space allocated for these modules will then be reclaimed. Symbol definitions of these modules will also be invalidated.

Storage for both the text and the data segments of the dynamically linked modules is allocated from the heap of the executing process, thus they are not write protected. Functions and global variables of these modules have to be accessed through pointers.

Dld_init initializes the symbol table and loads the symbol definitions of the executing process. It must be called before any module is linked. The argument path is a string containing the path name of the executable file of the executing process. Dld_init returns 0 if the call succeeds, an non-zero error code if it fails.

Dld_link dynamically loads an object or library file specified by the string path into the calling process' address space. If path points to a library file, only those routines referenced by some of the already linked-in modules will be loaded. Dld_Link returns 0 if the call succeeds, a non-zero error code if it fails.

Dld_get_symbol returns the address where the global symbol id is loaded. Id can be any global symbol defined by the executing process or the dynamically linked-in modules. If id is not defined, a 0 is returned.

Dld_get_func works in a similar way as dld_get_symbol, except that the symbol specified by func must be an identifier of a function. The value returned can be used as the entry point to the named function. If func is not defined, or if func does not define a function, a 0 is returned.

Dld_unlink_by_file removes the text and data segment, as well as the symbol definitions of a previously linked-in module. Path should either be the same name passed to dld_link when the module was linked, or the absolute path name to that file. If force is zero, the named file will only be unlinked if none of the symbols it defined is referenced by any other modules. If force is non-zero, the named file will be unlinked unconditionally.

If a successful unlinking of the file leaves any other modules unreferenced, these modules will also be unlinked automatically.

Dld_unlink_by_symbol works in the same way as dld_unlink_by_file except that it automatically searches for the module that defined the symbol id and then unlinks it.

Both dld_unlink_by_file and dld_unlink_by_symbol return 0 if the call succeeds, non-zero error code if it fails.

Dld_function_executable_p returns non-zero if func is the name of a function and it can be safely executed, otherwise it returns 0. A function can be safely executed when all global symbols it references are defined and all other functions that it might call can also be safely executed.

ERRORS
If a call to the dld functions fails, one of the following error code will be returned.

DLD_ENOFILE
    The specified file cannot be opened.

DLD_EBADMAGIC
    The specified object or library file contains a bad magic number.

DLD_EBADHEADER
    The specified object or library file contains a bad exec header.

DLD_ENOTEXT
    The specified object or library file has a premature eof in text section.

DLD_ENOSYMBOLS
    The specified object or library file has a premature end of file in symbols table.

DLD_ENOSTRINGS
    The specified object or library file contains a bad string table.

DLD_ENOTXTRELOC
    The specified object or library file has a premature eof in the text relocation section.

DLD_ENODATA
    The specified object or library file has a premature eof in the data section.

DLD_ENODATRELOC
    The specified object or library file has a premature eof in the data relocation section.

DLD_EMULTDEFS
    A symbol is multiple defined. Either the specified object or library file defines the same symbol more than once, or that symbol has already been defined by some other module already loaded.

DLD_EBADLIBRARY
    The specified library file is a malformed library archive.

DLD_EBADOBJECT
    The specified file is neither a relocatable object file nor an object library.

DLD_EBADRELOC
    The relocation information contained in the specified file is bad.

DLD_ENOMEMORY
    There is not enough virtual memory to hold the codes of the specified file.

DLD_EUNDEFSYM
    The specified symbol is not defined.

RESTRICTIONS
The executable files of programs that use this package should not be stripped, otherwise the symbol table information for resolving external references will not be available and functions or global variables cannot be shared by the new modules.

BUGS
When a function is being unlinked, only the storage for the text and data segments is reclaimed, and its corresponding symbol definitions invalidated. No other cleanup work is done. For example, files opened by this function will not be closed, and memory blocks allocated by this function are not reclaimed.

SEE ALSO
ar(1), cc(1), ranlib(1), ld(1), which(3)

AUTHOR
Wilson Ho - Division of Computer Science, EECS Department, University of California at Davis.