Support Interface Functions

All ld-support interfaces 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.

This function is called before compressed sections are decompressed, complicating the task of examining the data or replacing the data. For this reason, it is recommended that support libraries defer the examination and possible replacement of section data to ld_section().

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. However, sections containing compressed data are decompressed before this function is called.

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);

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 ELF Section Attribute Flags.

ld_input_done()

This function, which was added in version LD_SUP_VERSION2, is called when input file processing is complete.

At this point, all input sections have been assigned to the output file image. In addition, the information required to create and update this image, has been collected in preparation to apply to the initial image. Great care should be exercised with any attempt by ld_input_done() to alter any data recorded from previous support routines. Any change to the identification or relationship of sections will be lost, or may compromise the creation of the output file image. Minor updates, such as the addition of section data that does not require relocation, or affect existing relocations, can be applied.

void ld_input_done(uint_t *flags);

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.