Capability Specific Shared Objects

The dynamic token $CAPABILITY can be used to specify a directory in which capability specific shared objects exist. This token is available for filters and dependencies. As this token can expand to multiple objects, its use with dependencies is controlled. Dependencies obtained with dlopen(3C), can use this token with the mode RTLD_FIRST. Explicit dependencies that use this token will load the first appropriate dependency found.

The path name specification must consist of a full path name terminated with the $CAPABILITY token. Shared objects that exist in the directory that is specified with the $CAPABILITY token are inspected at runtime. These objects should indicate their capability requirements. See Identifying Capability Requirements. Each object is validated against the capabilities that are available to the process. Those objects that are applicable for use with the process, are sorted in descending order of their capability values. These sorted filtees are used to resolve symbols that are defined within the filter.

Filtees within the capabilities directory have no naming restrictions. The following example shows how the auxiliary filter libfoo.so.1 can be designed to access hardware capability filtees.

$ LD_OPTIONS='-f /opt/ISV/lib/cap/$CAPABILITY' \
cc -o libfoo.so.1 -G -K pic -h libfoo.so.1 -R. foo.c
$ elfdump -d libfoo.so.1 | egrep 'SONAME|AUXILIARY'
       [2]  SONAME            0x1                 libfoo.so.1
       [3]  AUXILIARY         0x96                /opt/ISV/lib/cap/$CAPABILITY
$ elfdump -H /opt/ISV/lib/cap/*

/opt/ISV/lib/cap/filtee.so.3:

Capabilities Section:  .SUNW_cap

 Object Capabilities:
     index  tag               value
       [0]  CA_SUNW_HW_1     0x1000  [ SSE2 ]

/opt/ISV/lib/cap/filtee.so.1:

Capabilities Section:  .SUNW_cap

 Object Capabilities:
     index  tag               value
       [0]  CA_SUNW_HW_1     0x40  [ MMX ]

/opt/ISV/lib/cap/filtee.so.2:

Capabilities Section:  .SUNW_cap

 Object Capabilities:
     index  tag               value
       [0]  CA_SUNW_HW_1     0x800  [ SSE ]

If the filter libfoo.so.1 is processed on a system where the MMX and SSE hardware capabilities are available, the following filtee search order occurs.

$ cc -o prog prog.c -R. -lfoo
$ LD_DEBUG=symbols prog
....
01233: symbol=foo;  lookup in file=libfoo.so.1  [ ELF ]
01233: symbol=foo;  lookup in file=cap/filtee.so.2  [ ELF ]
01233: symbol=foo;  lookup in file=cap/filtee.so.1  [ ELF ]
....

Note that the capability value for filtee.so.2 is greater than the capability value for filtee.so.1. filtee.so.3 is not a candidate for inclusion in the symbol search, as the SSE2 capability is not available.

Reducing Filtee Searches

The use of $CAPABILITY within a filter enables one or more filtees to provide implementations of interfaces that are defined within the filter.

All shared objects within the specified $CAPABILITY directory are inspected to validate their availability, and to sort those found appropriate for the process. Once sorted, all objects are loaded in preparation for use.

A filtee can be built with the link-editor's -z endfiltee option to indicate that it is the last of the available filtees. A filtee identified with this option, terminates the sorted list of filtees for that filter. No objects sorted after this filtee are loaded for the filter. From the previous example, if the filter.so.2 filtee was tagged with -z endfiltee, the filtee search would be as follows.

$ LD_DEBUG=symbols prog
....
01424: symbol=foo;  lookup in file=libfoo.so.1  [ ELF ]
01424: symbol=foo;  lookup in file=cap/filtee.so.2  [ ELF ]
....