NAME

rld_load, rld_unload, rld_lookup, 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,
char ∗∗object_filenames,
char ∗output_filename);
extern long rld_unload(
NXStream ∗stream);
extern long rld_lookup(
NXStream ∗stream,
char ∗symbol_name,
unsigned long ∗value);
extern long rld_unload_all(
NXStream ∗stream,
long deallocate_sets);
extern long rld_load_basefile(
NXStream ∗stream,
char ∗base_filename);
extern void rld_address_func(
unsigned long (∗func)(unsigned long 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 shared library and wants to make all the symbols in that shared library available to the objects it loads it must force all of those symbols into the executable.  The way this can be done easily 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 object 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 automaticly.  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.  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_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_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.  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.  —  April 12, 1990