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.
