Parent Objects

Ali Bahrami — Monday November 26, 2012

Surfing with the Linker-Aliens

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.

Surfing with the Linker-Aliens

Published Elsewhere

https://blogs.oracle.com/ali/entry/parent_objects/
https://blogs.oracle.com/ali/parent-objects/

Surfing with the Linker-Aliens

[24] Ancillary Objects Blog Index (ali) [26] Solaris 11.4 Beta Is Available