ELF_UPDATE(3) BSD Library Functions Manual ELF_UPDATE(3)NAMEelf_update — update an ELF descriptor
LIBRARY
library “libelf”
SYNOPSIS
#include <libelf.h>
off_t
elf_update(Elf *elf, Elf_Cmd cmd);
DESCRIPTION
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 applica‐
tion assumes full responsibility for the layout of the ELF object. If
this flag 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 struc‐
ture 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 executa‐
bles.
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 FreeBSD exe‐
cutables, this field should be set to
ELFOSABI_FREEBSD.
e_machine Set to the desired machine architecture, one
of the EM_* values 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 contain‐
ing section names.
e_type Set to the type of the ELF object, one of the
ET_* values 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 responsi‐
bility:
sh_addr Set to the physical memory address where the sec‐
tion 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 con‐
taining fixed size elements, or set to zero for
sections without fixed size elements. If the
application is not managing file layout, it may
leave this field as zero for those sections whose
types known to the library.
sh_flags Set to the desired section flags.
sh_info Set as described in elf(5).
sh_link Set as described in elf(5).
sh_name 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 sec‐
tion's contents.
sh_size If the application is managing the file layout, it
must set this field to the file size of the sec‐
tion'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_fill(3).
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 Elf_Scn and Elf_Data descriptors associated with descrip‐
tor 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 suc‐
cessful, or -1 if an error occurred.
ERRORS
This function may fail with the following errors:
[ELF_E_ARGUMENT] Argument elf was null.
[ELF_E_ARGUMENT] Argument cmd was not recognized.
[ELF_E_ARGUMENT] The argument elf was not a descriptor for an ELF
object.
[ELF_E_CLASS] The e_ident[EI_CLASS] field of the executable header of
argument elf did not match the class of the file.
[ELF_E_DATA] An Elf_Data descriptor contained in argument elf speci‐
fied a type incompatible with its containing section.
[ELF_E_HEADER] The ELF header in argument elf requested a different
byte order from the byte order already associated with
the file.
[ELF_E_IO] An I/O error was encountered.
[ELF_E_LAYOUT] An Elf_Data descriptor contained in argument elf speci‐
fied an alignment incompatible with its containing sec‐
tion.
[ELF_E_LAYOUT] Argument elf contained section descriptors that over‐
lapped in extent.
[ELF_E_LAYOUT] Argument elf contained section descriptors that were
incorrectly aligned or were too small for their data.
[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.
[ELF_E_MODE] An ELF_C_WRITE operation was requested with an ELF
descriptor that was not opened for writing or updating.
[ELF_E_SECTION] Argument elf contained a section with an unrecognized
type.
[ELF_E_SECTION] The section header at index SHN_UNDEF had an illegal
section type.
[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.
[ELF_E_VERSION] Argument elf had an unsupported version or contained an
Elf_Data descriptor with an unsupported version.
SEE ALSOelf(3), elf32_getehdr(3), elf32_getphdr(3), elf32_newehdr(3),
elf32_newphdr(3), elf64_getehdr(3), elf64_getphdr(3), elf64_newehdr(3),
elf64_newphdr(3), elf_cntl(3), elf_fill(3), elf_flagehdr(3),
elf_flagelf(3), elf_getdata(3), elf_getscn(3), elf_newdata(3),
elf_newscn(3), elf_rawdata(3), gelf(3), gelf_newehdr(3), gelf_newphdr(3),
elf(5)BSD March 19, 2008 BSD
