Manual pages › ELF library (3E)
elf_update(3E)
update an ELF descriptor
From the original Amiga UNIX 2.1 manual. Some things it mentions may not be in this release.
NAME
elf_update - update an ELF descriptor
SYNOPSIS
cc [flag ...] file ... -lelf [library ...] #include <libelf.h> off_t elf_update(Elf *elf, Elf_Cmd cmd);
DESCRIPTION
elf_update causes the library to examine the information associated with an ELF descriptor, elf, and to recalculate the structural data needed to generate the file's image. cmd may have the following values.
ELF_C_NULL This value tells elf_update to recalculate various values, updating only the ELF descriptor's memory structures. Any modified structures are flagged with the ELF_F_DIRTY bit. A program thus can update the structural information and then reexamine them without changing the file associated with the ELF descriptor. Because this does not change the file, the ELF descriptor may allow reading, writing, or both reading and writing [see elf_begin(3E)].
ELF_C_WRITE If cmd has this value, elf_update duplicates
its ELF_C_NULL actions and also writes any
``dirty'' information associated with the
ELF descriptor to the file. That is, when a
program has used elf_getdata or the elf_flag
facilities to supply new (or update exist-
ing) information for an ELF descriptor,
those data will be examined, coordinated,
translated if necessary [see elf_xlate(3E)],
and written to the file. When portions of
the file are written, any ELF_F_DIRTY bits
are reset, indicating those items no longer
need to be written to the file [see
elf_flag(3E)]. The sections' data are writ-
ten in the order of their section header
entries, and the section header table is
written to the end of the file.
When the ELF descriptor was created with
elf_begin, it must have allowed writing the
file. That is, the elf_begin command must
have been either ELF_C_RDWR or ELF_C_WRITE.
If elf_update succeeds, it returns the total
size of the file image (not the memory
image), in bytes. Otherwise an error
occurred, and the function returns -1. When
updating the internal structures, elf_update
sets some members itself. Members listed
below are the application's responsibility
and retain the values given by the program.
Member Notes
_________________________________________________________
e_ident[EI_DATA]| Library controls other e_ident values
e_type |
e_machine |
e_version |
ELF Header e_entry |
e_phoff | Only when ELF_F_LAYOUT asserted
e_shoff | Only when ELF_F_LAYOUT asserted
e_flags |
e_shstrndx |
_________________|_______________________________________
__Member_______________Notes____________
p_type | The application controls all
p_offset| program header entries
p_vaddr |
p_paddr |
Program Header p_filesz|
p_memsz |
p_flags |
p_align |
_________|______________________________
Member Notes
_______________________________________________
sh_name |
sh_type |
sh_flags |
sh_addr |
Section Header sh_offset | Only when ELF_F_LAYOUT asserted
sh_size | Only when ELF_F_LAYOUT asserted
sh_link |
sh_info |
sh_addralign| Only when ELF_F_LAYOUT asserted
sh_entsize |
_____________|_________________________________
Member Notes
____________________________________________
d_buf |
d_type |
Data Descriptor d_size |
d_off | Only when ELF_F_LAYOUT asserted
d_align |
d_version|
__________|_________________________________
Note the program is responsible for two par-
ticularly important members (among others)
in the ELF header. The e_version member
controls the version of data structures
written to the file. If the version is
EV_NONE, the library uses its own internal
version. The e_ident[EI_DATA] entry con-
trols the data encoding used in the file.
As a special case, the value may be ELFDA-
TANONE to request the native data encoding
for the host machine. An error occurs in
this case if the native encoding doesn't
match a file encoding known by the library.
Further note that the program is responsible
for the sh_entsize section header member.
Although the library sets it for sections
with known types, it cannot reliably know
the correct value for all sections. Conse-
quently, the library relies on the program
to provide the values for unknown section
type. If the entry size is unknown or not
applicable, the value should be set to zero.
When deciding how to build the output file,
elf_update obeys the alignments of indivi-
dual data buffers to create output sections.
A section's most strictly aligned data
buffer controls the section's alignment.
The library also inserts padding between
buffers, as necessary, to ensure the proper
alignment of each buffer.
SEE ALSO
elf(3E), elf_begin(3E), elf_flag(3E), elf_fsize(3E), elf_getdata(3E), elf_getehdr(3E), elf_getshdr(3E), elf_xlate(3E).
NOTE
As mentioned above, the ELF_C_WRITE command translates data as necessary, before writing them to the file. This translation is not always transparent to the application program. If a program has obtained pointers to data associated with a file [for example, see elf_getehdr(3E) and elf_getdata(3E)], the program should reestablish the pointers after calling elf_update. As elf_begin(3E) describes, a program may
``update'' a COFF file to make the image consistent for ELF . The ELF_C_NULL command updates only the memory image; one can use the ELF_C_WRITE command to modify the file as well. Absolute executable files (a.out files) require special alignment, which cannot normally be preserved between COFF and ELF . Consequently, one may not update an executable COFF file with the ELF_C_WRITE command (though ELF_C_NULL is allowed).