NAME

rld_load, rld_load_from_memory, rld_unload, rld_lookup, rld_forget_symbol, rld_unload_all, rld_load_basefile, rld_address_func − dynamicly link edit and load object files

SYNOPSIS

#include <rld.h>
extern long rld_load(
NXStream ∗stream,
struct mach_header ∗∗header_addr,
const char ∗ const ∗object_filenames,
const char ∗output_filename);
extern long rld_load_from_memory(
NXStream ∗stream,
struct mach_header ∗∗header_addr,
const char ∗object_name,
char ∗object_addr,
long ∗object_size,
const char ∗output_filename);
extern long rld_unload(
NXStream ∗stream);
extern long rld_lookup(
NXStream ∗stream,
const char ∗symbol_name,
unsigned long ∗value);
extern long rld_forget_symbol(
NXStream ∗stream,
const char ∗symbol_name);
extern long rld_unload_all(
NXStream ∗stream,
long deallocate_sets);
extern long rld_load_basefile(
NXStream ∗stream,
const char ∗base_filename);
extern void rld_address_func(
unsigned long (∗func)(unsigned long size, unsigned long headers_size));

DESCRIPTION

rld_load link edits and loads the specified object filenames in the NULL terminated array of object file names, object_filenames, into the program that called it (or can be use to load into another program).  An object name can be an archive and if so only those members defining undefined symbols will be loaded. 

If the program wishes to allow the loaded object files to use symbols from itself it must be built with the −seglinkedit link editor, ld(1), option to have its symbol table mapped into memory.

The symbol table may be trimmed to exactly which symbols are allowed to be referenced by loaded objects with the use of the −s filename option to strip(1). For the routines described here only global symbols are used so the −x option to the link editor, ld(1), or strip(1) can be used to save space in the final program and vastly decrease the time the first call to rld_load takes (and all first calls after rld_unload_all).  This is because rld_load must go through all the symbols of the program and if the program has been compiled for debugging for example it can take orders of magnitude longer because of the great number of symbols. 

Since only the symbols that appear in the executable program can be used by the objects loaded with rld_load if the program uses a library and wants to make all the symbols in that library available to the objects it loads it must force all of the library symbols into the executable.  This can be done for all libraries with the ld(1) −all_load flag when building the executable.  For libraries that are not shared this will copy all the library code into the executable.  So this may only want to be done for the shared libraries where the library code is not copied into the executable.  The way this can be done easily for shared libraries is to have the executable program reference the shared library reference symbol for each of the shared libraries it uses.  The shared library reference symbol has the name base name of the target library up to the first ’.’.  For the target shared library /usr/shlib/libsys_s.B.shlib the shared library reference symbol name is libsys_s.  This name intentionally does not start with an underscore, to reference the above symbol for example the ld(1) −u libsys_s option would be used when linking the program and this option would appear on the link edit command line before the library.  If the target shared library changes and new routines and data are added and the program wishes to make them available to the objects it loads with rld_load the program must be relinked against the host shared library that matches the target shared library.  This must be done this way to avoid link editing and loading errors that would otherwise fail to run correctly in very hard to detect ways. 

The set of object files being loaded will only be successful if there are no link edit errors (undefined symbols, etc.).  If an error occurs the set of object files is unloaded automatically.  If errors occur and the value specified for stream is not NULL error messages are printed on that stream.  If the link editing and loading is successful the address of the header of what was loaded is returned through the pointer header_addr it if is not NULL.  If rld_load is successful and the parameter output_filename is not NULL then an object file is written to that filename and can be used with the gdb(1) add-file command to debug the code in the dynamicly loaded set of objects.  When the program being debugged is using rld to load into itself the debugger knows how to get the symbols automaticly in most cases and the output_filename parameter is not needed.  If the program being debugged has some other program using rld loading into it or the objects being specified do not contain full paths the debugger can’t do this automaticly.  rld_load returns 1 for success and 0 for failure.  If a fatal system error (out of memory, etc.) occurs then all future calls of this and all routines described here will fail. 

rld_load_from_memory() provides a similar function as rld_load() but works on memory rather than a file.  The argument object_name is the name of associated with the memory and is used for messages (must not be NULL). The arguments object_addr and object_size are the memory address the object file is at and the size of that object file.  rld_load_from_memory() only allows one object file (not an archive) to be loaded. 

rld_unload() unlinks and unloads that last object set that was loaded.  It returns 1 if it is successful and 0 otherwise.  If any errors occur and the specified stream, stream, is not zero the error messages are printed on that stream.  It is the caller’s responsibility not to have any pointers into the data areas of the object set and to deallocate any memory that set of objects may have allocated. 

rld_lookup() looks up the specified symbol name, symbol_name, and returns its value indirectly through the pointer specified, value.  It returns 1 if it finds the symbol and 0 otherwise.  If any errors occur and the specified stream, stream, is not zero the error messages are printed on that stream (for this routine only internal errors could result). 

rld_forget_symbol() causes this package to forget the existence of the specified symbol name, symbol_name.  This allows a new object to be loaded and define this symbol.  All objects loaded before this call will continue to use the value of the symbol in effect at the time the object was loaded.  It returns 1 if it finds the symbol and 0 otherwise.  If any errors occur and the specified stream, stream, is not zero the error messages are printed on that stream (for this routine only internal errors could result). 

rld_unload_all() clears out all allocated data structures used by these routines.  If the parameter deallocate_sets is non-zero it also unloads all object sets that were loaded.  If deallocate_sets is zero the object sets are not unloaded and the program can continue to use the code and data loaded but further calls routines here will no longer know about symbols in those sets.  If objects sets are not to be allowed access to each others symbols an rld_unload_all call between calls to rld_load allows objects sets to be loaded without them worrying about global symbol names clashing.  rld_unload_all returns 1 if it is successful and 0 otherwise.  If any errors occur and the specified stream, stream, is not zero the error messages are printed on that stream. 

rld_load_basefile is passed a file name, base_filename, that is to be used as the base file, that is it’s symbol table is taken as the basis for subsequent rld_load’s.  This must be done before any call to rld_load.  Or can be done after a call to rld_unload_all which unloads the base file.  This call is intended to be used when a program is dynamicly loading object sets into a program other than itself were base_filename contains the symbol table of the target program.  The routine rld_address_func described next would also be used. 

rld_address_func is passed a pointer to a function, func, that is called from rld_load with the size of the memory required to for the object set being loaded and the size of the headers included in that size.  func returns the address where the output is to link edited to.  This call is intended to be used when a program is dynamicly loading object sets into a program other than itself and allows it to pick the place in the address space of the target program. 
 

SEE ALSO

ld(1), strip(1), gdb(1)
 

BUGS

There exist one semantic link edit problem with respect to common symbols.  If a set of object files are loaded that have common symbols left after the symbols have been merged rld_load then has to allocate storage for these symbols for the code to run without error.  The problem occurs if on a later call to rld_load one of the common symbols that rld_load allocated appears in an object file as a defining symbol (not a common or an undefined).  In this case rld_load will report the symbol as being multiply defined.  However if this combination of object files were staticly linked no error would occur. 

NeXT Computer, Inc.  —  March 7, 1992