Function
elf_update ();
causes the library to recalculate the structure of an ELF
object and optionally write out the image of the object
to file.
Argument
elf
is a descriptor to an ELF object.
Argument
cmd
can take on the following values:
ELF_C_NULL
The library will recalculate structural information flagging
modified structures with the
ELF_F_DIRTY
flag, but will not write back data to the underlying file image.
ELF_C_WRITE
The library will recalculate structural information and will
also write the new image to the underlying file.
File Layout
If the
ELF_F_LAYOUT
flag has been set on the ELF descriptor, the application assumes full
responsibility for the layout of the ELF object.
If this bit is not set, the ELF library will compute the layout of the
file from its associated section descriptors.
It is the application's responsibility to manage the the following
structure members in the ELF file:
"Executable Header"
The ELF executable header is described in
elf(5).
The following members of the ELF executable header are the application's
responsibility:
e_entry
Set to the desired entry address for executables.
e_flags
Set to the desired processor specific flags.
e_ident[EI_DATA]
Must be set to one of
ELFDATA2LSB
or
ELFDATA2MSB
e_ident[EI_OSABI]
Set to the OS ABI desired.
For
Fx executables, this field should be set to
ELFOSABI_FREEBSD
e_machine
Set to the desired machine architecture, one of the
EM_*
values in
In sys/elf_common.h .
e_phoff
If the application is managing the object's layout, it must
set this field to the file offset of the ELF program header table.
e_shoff
If the application is managing the object's layout, it must
set this field to the file offset of the ELF section header table.
e_shstrndx
Set to the index of the string table containing
section names.
e_type
Set to the type of the ELF object, one of the
ET_*
values in
In sys/elf_common.h .
e_version
Set to the desired version of the ELF object.
"Program Header"
All fields of the entries in the program header table are
under application control.
"Section Header"
The ELF section header is described in
elf(5).
The following members of the ELF section header are the
application's responsibility:
sh_addr
Set to the physical memory address where the section should reside.
sh_addralign
If the application is managing the file layout, it must set this
field to the desired alignment for the section's contents.
This value must be a power of two.
sh_entsize
Set to the size of each entry, for sections containing fixed size
elements, or set to zero for sections without fixed size elements.
For section contents of types known to the library, the application
may leave this field as zero.
Set to the index of the section's name in the string table containing
section names.
sh_offset
If the application is managing the file layout, it must set this
field to the file offset of the section's contents.
sh_size
If the application is managing the file layout, it must set this
field to the file size of the section's contents.
sh_type
Set to the type of the section.
Gaps in the coverage of the file's contents will be set to the fill value
specified by
elf_fill3.
If the application has requested full control over the file's layout by
setting the
ELF_F_LAYOUT
flag on the ELF descriptor, it should ensure that there are no
gaps in the coverage of the file's contents.
All pointers to
Vt Elf_Scn
and
Vt Elf_Data
descriptors associated with descriptor
elf
should be considered as invalid after a call to
elf_update (.);
RETURN VALUES
Function
elf_update ();
returns the total size of the file image if successful, or -1 if an
error occurred.
ERRORS
This function may fail with the following errors:
Bq Er ELF_E_ARGUMENT
Argument
elf
was null.
Bq Er ELF_E_ARGUMENT
Argument
cmd
was not recognized.
Bq Er ELF_E_ARGUMENT
The argument
elf
was not a descriptor for an ELF object.
Bq Er ELF_E_CLASS
The
e_ident[EI_CLASS]
field of the executable header of argument
elf
did not match the class of the file.
Bq Er ELF_E_DATA
An
Vt Elf_Data
descriptor contained in argument
elf
specified a type incompatible with its containing section.
Bq Er ELF_E_HEADER
The ELF header in argument
elf
requested a different byte order from the byte order already
associated with the file.
Bq Er ELF_E_IO
An I/O error was encountered.
Bq Er ELF_E_LAYOUT
An
Vt Elf_Data
descriptor contained in argument
elf
specified an alignment incompatible with its containing section.
Bq Er ELF_E_LAYOUT
Argument
elf
contained section descriptors that overlapped in extent.
Bq Er ELF_E_LAYOUT
Argument
elf
contained section descriptors that were incorrectly aligned or were
too small for their data.
Bq Er ELF_E_LAYOUT
The flag
ELF_F_LAYOUT
was set on the Elf descriptor and the section header table overlapped
an extent in the object mapped by a section descriptor.
Bq Er ELF_E_MODE
An
ELF_C_WRITE
operation was requested with an ELF descriptor that was not opened for
writing or updating.
Bq Er ELF_E_SECTION
Argument
elf
contained a section with an unrecognized type.
Bq Er ELF_E_SECTION
The section header at index
SHN_UNDEF
had an illegal section type.
Bq Er ELF_E_SEQUENCE
An
ELF_C_WRITE
operation was requested after a prior call to
elf_cntl (elf ELF_C_FDDONE);
disassociated the ELF descriptor
elf
from its underlying file.
Bq Er ELF_E_VERSION
Argument
elf
had an unsupported version or contained an
Vt Elf_Data
descriptor with an unsupported version.
