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 eitherET_DYN
,ET_REL
, orET_EXEC
, as defined insys/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 theld_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 ofelf_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 thepname
. Bothpname
andfname
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 told_open
() is set to the value-1
if the link-editor is unable to allowld_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 told_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 eitherELF_K_AR
, orELF_K_ELF
, as defined inlibelf.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 eitherELF_K_AR
, orELF_K_ELF
, as defined inlibelf.h
. Theflags
field indicates how the link-editor obtained the file. This field can contain the same definitions as theflags
field forld_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 fromld_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 fromld_input_section
() to process the section.You can modify the data by reallocating the data and reassigning the
Elf_Data
buffer'sd_buf
pointer. Any modification to the data should ensure the correct setting of theElf_Data
buffer'sd_size
element. For input sections that become part of the output image, setting thed_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 auint_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);
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'sd_buf
pointer. Any modification to the data should ensure the correct setting of theElf_Data
buffer'sd_size
element. For input sections that become part of the output image, setting thed_size
element to zero effectively removes the data from the output image.Note:
Sections that are removed from the output file are not reported told_section
(). Sections are stripped using the link-editor's-z strip-class
option. Sections are discarded due toSHT_SUNW_COMDAT
processing orSHF_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);
The
flags
field points to auint_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 theexit
(2) code that will be returned by the link-editor and is eitherEXIT_FAILURE
orEXIT_SUCCESS
, as defined instdlib.h
.