Support for Parent Objects was added in Solaris 11 Update 1.
The following material is adapted from the PSARC arc case, and the
Solaris Linker and Libraries Manual.
A "plugin" is a shared object, usually loaded via dlopen(), that is
used by a program in order
to allow the end user
to add functionality
to the program. Examples of plugins include those used by web browsers
(flash, acrobat, etc), as well as mdb and elfedit modules. The object
that loads the plugin at runtime is called the "parent object". Unlike
most object dependencies, the parent is not identified by name, but
by its status as the object doing the load.
Historically, building a good plugin is has been more complicated than
it should be:
A parent and its plugin usually share a 2-way dependency: The plugin
provides one or more routines for the parent
to call, and the parent
supplies support routines for use by the plugin for things like memory
allocation and error reporting.
It is a best practice
to build all objects, including plugins, with
the -z defs option, in order
to ensure that the object specifies all
of its dependencies, and is self contained. However:
The parent is usually an executable, which cannot be linked
to via the usual library mechanisms provided by the link editor.
Even if the parent is a shared object, which could be a
normal library dependency
to the plugin, it may be desirable
to build plugins that can be used by more than one parent,
in which case embedding a dependency NEEDED entry for one
of the parents is undesirable.
The usual way
to build a high quality plugin with -z defs uses a special
mapfile provided by the parent. This mapfile defines the parent routines,
specifying the PARENT attribute (see example below). This works, but is
inconvenient, and error prone. The symbol table in the parent already
describes what it makes available
to plugins — ideally
the plugin would obtain that information directly rather than from a
separate mapfile.
The new -z parent option
to ld allows a plugin
to link
to the parent and
access the parent symbol table. This differs from a typical dependency:
No NEEDED record is created.
The relationship is recorded as a logical connection
to the
parent, rather than as an explicit object name
However, it operates in the same manner as any other dependency
in terms of making symbols available
to the plugin.
When the -z parent option is used, the link-editor records the basename
of the parent object in the dynamic section, using the new tag DT_SUNW_PARENT.
This is an informational tag, which is not used by the runtime linker
to locate the parent, but which is available for diagnostic purposes.
The ld(1) manpage documentation for the -z parent option is:
-z parent=object
Specifies a "parent object", which can be an executable or shared
object, against which
to link the output object. This option is
typically used when creating "plugin" shared objects intended
to
be loaded by an executable at runtime via the dlopen() function.
The symbol table from the parent object is used
to satisfy
references from the plugin object. The use of the -z parent option
makes symbols from the object calling dlopen() available
to the
plugin.
Example
For this example, we use a main program, and a plugin. The parent
provides a function named parent_callback() for the plugin
to call.
The plugin provides a function named plugin_func()
to the parent:
% cat main.c
#include <stdio.h>
#include <dlfcn.h>
#include <link.h>
void
parent_callback(void)
{
printf("plugin_func() has called parent_callback()\n");
}
int
main(int argc, char **argv)
{
typedef void plugin_func_t(void);
void *hdl;
plugin_func_t *plugin_func;
if (argc != 2) {
fprintf(stderr, "usage: main plugin\n");
return (1);
}
if ((hdl = dlopen(argv[1], RTLD_LAZY)) == NULL) {
fprintf(stderr, "unable
to load plugin: %s\n", dlerror());
return (1);
}
plugin_func = (plugin_func_t *) dlsym(hdl, "plugin_func");
if (plugin_func == NULL) {
fprintf(stderr, "unable
to find plugin_func: %s\n",
dlerror());
return (1);
}
(*plugin_func)();
return (0);
}
% cat plugin.c
#include <stdio.h>
extern void parent_callback(void);
void
plugin_func(void)
{
printf("parent has called plugin_func() from plugin.so\n");
parent_callback();
}
Building this in the traditional manner, without -zdefs:
% cc -o main main.c
% cc -G -o plugin.so plugin.c
% ./main ./plugin.so
parent has called plugin_func() from plugin.so
plugin_func() has called parent_callback()
As noted above, when building any shared object, the -z defs option
is recommended, in order
to ensure that the object is self contained
and specifies all of its dependencies. However, the use of -z defs
prevents the plugin object from linking due
to the unsatisfied symbol
from the parent object:
% cc -zdefs -G -o plugin.so plugin.c
Undefined first referenced
symbol in file
parent_callback plugin.o
ld: fatal: symbol referencing errors. No output written
to plugin.so
A mapfile can be used
to specify
to ld that the parent_callback symbol is
supplied by the parent object.
% cat plugin.mapfile
$mapfile_version 2
SYMBOL_SCOPE {
global:
parent_callback { FLAGS = PARENT };
};
% cc -zdefs -Mplugin.mapfile -G -o plugin.so plugin.c
However, the -z parent option
to ld is the most direct solution
to
this problem, allowing the plugin
to actually link against the parent
object, and obtain the available symbols from it. An added benefit of
using -z parent instead of a mapfile, is that the name of the parent
object is recorded in the dynamic section of the plugin, and can be displayed
by the file utility:
% cc -zdefs -zparent=main -G -o plugin.so plugin.c
% elfdump -d plugin.so | grep PARENT
[0] SUNW_PARENT 0xcc main
% file plugin.so
plugin.so: ELF 32-bit LSB dynamic lib 80386 Version 1,
parent main, dynamically linked, not stripped
% ./main ./plugin.so
parent has called plugin_func() from plugin.so
plugin_func() has called parent_callback()
We can also observe this in elfedit plugins on Solaris systems running
Solaris 11 Update 1 or newer:
% file /usr/lib/elfedit/dyn.so
/usr/lib/elfedit/dyn.so: ELF 32-bit LSB dynamic lib 80386 Version 1,
parent elfedit, dynamically linked, not stripped,
no debugging information available
Related Other Work
The GNU ld has an option named --just-symbols that can be used
in a similar manner:
--just-symbols=filename
Read symbol names and their addresses from filename, but
do not relocate it or include it in the output. This
allows your output file
to refer symbolically
to
absolute locations of memory defined in other programs.
You may use this option more than once.
-z parent is a higher level operation aimed specifically at simplifying
the construction of high quality plugins. Although it employs the same
operation, it differs from --just symbols in 2 significant ways:
There can only be one parent.
The parent is recorded in the created object, and can be
displayed by 'file', or other similar tools.
