Link-Editor Support Interface

The link-editor performs many operations including the opening of files and the concatenation of sections from these files. Monitoring, and sometimes modifying, these operations can often be beneficial to components of a compilation system.

This section describes the ld-support interface. This interface provides for input file inspection, and to some degree, input file data modification of those files that compose a link-edit. Two applications that employ this interface are the link-editor and the make(1S) utility. The link editor uses the interface to process debugging information within relocatable objects. The make utility uses the interface to save state information.

The ld-support interface is composed of a support library that offers one or more support interface routines. This library is loaded as part of the link-edit process. Any support routines that are found in the library are called at various stages of link-editing.

You should be familiar with the elf(3ELF) structures and file format when using this interface.

Invoking the Support Interface

The link-editor accepts one or more support libraries provided by either the SGS_SUPPORT environment variable or with the link-editor's -S option. The environment variable consists of a colon separated list of support libraries.

$ SGS_SUPPORT=support.so.1:support.so.2 cc ...

The -S option specifies a single support library. Multiple -S options can be specified.

$ LD_OPTIONS="-Ssupport.so.1 -Ssupport.so.2" cc ...

A support library is a shared object. The link-editor opens each support library, in the order the libraries are specified, using dlopen(3C). If both the environment variable and -S option are encountered, then the support libraries specified with the environment variable are processed first. Each support library is then searched, using dlsym(3C), for any support interface routines. These support routines are then called at various stages of link-editing.

A support library must be consistent with the ELF class of the link-editor being invoked, either 32–bit or 64–bit. See 32-Bit Environments and 64-Bit Environments for more details.

32–Bit Environments and 64–Bit Environments

As described in 32-Bit Environments and 64-Bit Environments, the 64–bit link-editor, ld(1), is capable of generating 32–bit objects. In addition, the 32–bit link-editor is capable of generating 64–bit objects. Each of these objects has an associated support interface defined.

The support interface for 64–bit objects is similar to the interface of 32–bit objects, but ends in a 64 suffix. For example ld_start() and ld_start64(). This convention allows both implementations of the support interface to reside in a single shared object of each class, 32–bit and 64–bit.

The SGS_SUPPORT environment variable can be specified with a _32 or _64 suffix, and the link-editor options -z ld32 and -z ld64 can be used to define -S option requirements. These definitions will only be interpreted, respectively, by the 32–bit or 64–bit class of the link-editor. This enables both classes of support library to be specified when the class of the link-editor might not be known.

Support Interface Functions

All ld-support interface are defined in the header file link.h. All interface arguments are basic C types or ELF types. The ELF data types can be examined with the ELF access library libelf. See elf(3ELF) for a description of libelf contents. The following interface functions are provided by the ld-support interface, and are described in their expected order of use.

ld_version()

This function provides the initial handshake between the link-editor and the support library.

uint_t ld_version(uint_t version);

The link-editor calls this interface with the highest version of the ld-support interface that the link-editor is capable of supporting. The support library can verify this version is sufficient for its use. The support library can then return the version that the support library expects to use. This version is normally LD_SUP_VCURRENT.

If the support library does not provide this interface, the initial support level LD_SUP_VERSION1 is assumed.

If the support library returns the version LD_SUP_VNONE, the link-editor silently unloads the support library, and proceeds without using it. If the returned version is greater than the ld-support interface the link-editor supports, a fatal error is issued, and the link-editor terminates execution. Otherwise, execution continues, using the support library at the specified ld-support interface version.

ld_start()

This function is called after initial validation of the link-editor command line. This function indicates the start of input file processing.

void ld_start(const char *name, const Elf32_Half type,
        const char *caller);

void ld_start64(const char *name, const Elf64_Half type,
        const char *caller);

name is the output file name being created. type is the output file type, which is either ET_DYN, ET_REL, or ET_EXEC, as defined in sys/elf.h. caller is the application calling the interface, which is normally /usr/bin/ld, or /usr/ccs/bin/ld.

ld_open()

This function is called for each file input to the link-edit. This function, which was added in version LD_SUP_VERSION3, provides greater flexibility than the ld_file() function. This function allows the support library to replace the file descriptor, ELF descriptor, together with the associated file names. This function provides the following possible usage scenarios.

• The addition of new sections to an existing ELF file. In this case, the original ELF descriptor should be replaced with a descriptor that allows the ELF file to be updated. See the ELF_C_RDWR argument of elf_begin(3ELF).

• The entire input file can be replaced with an alternative. In this case, the original file descriptor and ELF descriptor should be replaced with descriptors that are associated with the new file.

In both scenarios the path name and file name can be replaced with alternative names that indicate the input file has been modified.

void ld_open(const char **pname, const char **fname, int *fd,
    int flags, Elf **elf, Elf *ref, size_t off, Elf_Kind kind);
void ld_open64(const char **pname, const char **fname, int *fd,
    int flags, Elf **elf, Elf *ref, size_t off, Elf_Kind kind);

pname is the path name of the input file about to be processed. fname is the file name of the input file about to be processed. fname is typically the base name of the pname. Both pname and fname can be modified by the support library.

fd is the file descriptor of the input file. This descriptor can be closed by the support library, and a new file descriptor can be returned to the link-editor. A file descriptor with the value -1 can be returned to indicate that the file should be ignored.

---

Note - The fd passed to ld_open() is set to the value -1 if the link-editor is unable to allow ld_open() to close the file descriptor. The most common reason where this can occur is in the case of processing an archive member. If a value of -1 is passed to ld_open(), the descriptor can not be closed, nor should a replacement descriptor be returned by the support library.

---

The flags field indicates how the link-editor obtained the file. This field can be one or more of the following definitions.

• LD_SUP_DERIVED – The file name was not explicitly named on the command line. The file was derived from a -l expansion. Or, the file identifies an extracted archive member.

• LD_SUP_EXTRACTED – The file was extracted from an archive.

• LD_SUP_INHERITED – The file was obtained as a dependency of a command line shared object.

If no flags values are specified, then the input file has been explicitly named on the command line.

elf is the ELF descriptor of the input file. This descriptor can be closed by the support library, and a new ELF descriptor can be returned to the link-editor. An ELF descriptor with the value 0 can be returned to indicate that the file should be ignored. When the elf descriptor is associated with a member of an archive library, the ref descriptor is the ELF descriptor of the underlying archive file. The off represents the offset of the archive member within the archive file.

kind indicates the input file type, which is either ELF_K_AR, or ELF_K_ELF, as defined in libelf.h.

ld_file()

This function is called for each file input to the link-edit. This function is called before any processing of the files data is carried out.

void ld_file(const char *name, const Elf_Kind kind, int flags,
        Elf *elf);

void ld_file64(const char *name, const Elf_Kind kind, int flags,
        Elf *elf);

name is the input file about to be processed. kind indicates the input file type, which is either ELF_K_AR, or ELF_K_ELF, as defined in libelf.h. The flags field indicates how the link-editor obtained the file. This field can contain the same definitions as the flags field for ld_open().

• LD_SUP_DERIVED – The file name was not explicitly named on the command line. The file was derived from a -l expansion. Or, the file identifies an extracted archive member.

• LD_SUP_EXTRACTED – The file was extracted from an archive.

• LD_SUP_INHERITED – The file was obtained as a dependency of a command line shared object.

If no flags values are specified, then the input file has been explicitly named on the command line.

elf is the ELF descriptor of the input file.

ld_input_section()

This function is called for each section of the input file. This function, which was added in version LD_SUP_VERSION2, is called before the link-editor has determined whether the section should be propagated to the output file. This function differs from ld_section() processing, which is only called for sections that contribute to the output file.

void ld_input_section(const char *name, Elf32_Shdr **shdr,
        Elf32_Word sndx, Elf_Data *data, Elf *elf, unit_t flags);

void ld_input_section64(const char *name, Elf64_Shdr **shdr,
        Elf64_Word sndx, Elf_Data *data, Elf *elf, uint_t flags);

name is the input section name. shdr is a pointer to the associated section header. sndx is the section index within the input file. data is a pointer to the associated data buffer. elf is a pointer to the file's ELF descriptor. flags is reserved for future use.

Modification of the section header is permitted by reallocating a section header and reassigning the *shdr to the new header. The link-editor uses the section header information that *shdr points to upon return from ld_input_section() to process the section.

You can modify the data by reallocating the data and reassigning the Elf_Data buffer's d_buf pointer. Any modification to the data should ensure the correct setting of the Elf_Data buffer's d_size element. For input sections that become part of the output image, setting the d_size element to zero effectively removes the data from the output image.

The flags field points to a uint_t data field that is initially zero filled. No flags are currently assigned, although the ability to assign flags in future updates, by the link-editor or the support library, is provided.

ld_section()

This function is called for each section of the input file that is propagated to the output file. This function is called before any processing of the section data is carried out.

void ld_section(const char *name, Elf32_Shdr *shdr,
        Elf32_Word sndx, Elf_Data *data, Elf *elf);

void ld_section64(const char *name, Elf64_Shdr *shdr,
        Elf64_Word sndx, Elf_Data *data, Elf *elf);

name is the input section name. shdr is a pointer to the associated section header. sndx is the section index within the input file. data is a pointer to the associated data buffer. elf is a pointer to the files ELF descriptor.

You can modify the data by reallocating the data and reassigning the Elf_Data buffer's d_buf pointer. Any modification to the data should ensure the correct setting of the Elf_Data buffer's d_size element. For input sections that become part of the output image, setting the d_size element to zero effectively removes the data from the output image.

---

Note - Sections that are removed from the output file are not reported to ld_section(). Sections are stripped using the link-editor's -z strip-class option. Sections are discarded due to SHT_SUNW_COMDAT processing or SHF_EXCLUDE identification. See COMDAT Section, and Table 12-8.

---

ld_input_done()

This function, which was added in version LD_SUP_VERSION2, is called when input file processing is complete, but before the output file is laid out.

void ld_input_done(uint_t *flags);

The flags field points to a uint_t data field that is initially zero filled. No flags are currently assigned, although the ability to assign flags in future updates, by the link-editor or the support library, is provided.

ld_atexit()

This function is called when the link-edit is complete.

void ld_atexit(int status);

void ld_atexit64(int status);

status is the exit(2) code that will be returned by the link-editor and is either EXIT_FAILURE or EXIT_SUCCESS, as defined in stdlib.h.

Support Interface Example

The following example creates a support library that prints the section name of any relocatable object file processed as part of a 32–bit link-edit.

$ cat support.c
#include        <link.h>
#include        <stdio.h>
 
static int      indent = 0;
 
void
ld_start(const char *name, const Elf32_Half type,
    const char *caller)
{
        (void) printf("output image: %s\n", name);
}
 
void
ld_file(const char *name, const Elf_Kind kind, int flags,
    Elf *elf)
{
        if (flags & LD_SUP_EXTRACTED)
                indent = 4;
        else
                indent = 2;
 
        (void) printf("%*sfile: %s\n", indent, "", name);
}
 
void
ld_section(const char *name, Elf32_Shdr *shdr, Elf32_Word sndx,
    Elf_Data *data, Elf *elf)
{
        Elf32_Ehdr *ehdr = elf32_getehdr(elf);
 
        if (ehdr->e_type == ET_REL)
                (void) printf("%*s   section [%ld]: %s\n", indent,
                    "", (long)sndx, name);
}

This support library is dependent upon libelf to provide the ELF access function elf32_getehdr(3ELF) that is used to determine the input file type. The support library is built using the following.

$ cc -o support.so.1 -G -K pic support.c -lelf -lc

The following example shows the section diagnostics resulting from the construction of a trivial application from a relocatable object and a local archive library. The invocation of the support library, in addition to default debugging information processing, is brought about by the -S option usage.

$ LD_OPTIONS=-S./support.so.1 cc -o prog main.c -L. -lfoo

output image: prog
  file: /opt/COMPILER/crti.o
     section [1]: .shstrtab
     section [2]: .text
     .......
  file: /opt/COMPILER/crt1.o
     section [1]: .shstrtab
     section [2]: .text
     .......
  file: /opt/COMPILER/values-xt.o
     section [1]: .shstrtab
     section [2]: .text
     .......
  file: main.o
     section [1]: .shstrtab
     section [2]: .text
     .......
  file: ./libfoo.a
    file: ./libfoo.a(foo.o)
       section [1]: .shstrtab
       section [2]: .text
       .......
  file: /lib/libc.so
  file: /opt/COMPILER/crtn.o
     section [1]: .shstrtab
     section [2]: .text
     .......