Go to main content

Oracle® Solaris 11.4 Linkers and Libraries Guide

Exit Print View

Updated: October 2019
 
 

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.


Note - The original capabilities implementation was based solely on hardware capabilities. The token $HWCAP was used to select this capability processing. Capabilities have since been extended beyond hardware capabilities, and the $HWCAP token has been replaced by the $CAPABILITY token. For compatibility, the $HWCAP token is interpreted as an alias for the $CAPABILITY token.

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 Capability 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 ]
....