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(ELF)].
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 existing) information for an
ELF
descriptor, those data will be examined, coordinated, translated if necessary
[see
elf_xlate(ELF)],
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(ELF)].
The sections' data is written 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.
ELF_C_IMPURE_WRITE
When cmd is ELF_C_WRITE, elf_update attempts to write an image
of the entire output file in memory either by allocating storage from the heap
or by mapping an image of the output file.
This allocation, and the elf_update call, can fail if there is
insufficient memory to hold the entire file (or even the largest sections'
data after translation).
If ELF_C_IMPURE_WRITE is used instead, elf_update will, if
necessary, perform ``in place'' the memory-to-file translation in an
attempt to use the least amount of extra memory.
Thus, ELF_C_IMPURE_WRITE should only be used when the data will not
be examined after the call to elf_update.
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
ELF Header
e_ident[EI_DATA]
Library controls other e_ident values
e_type
e_machine
e_version
e_entry
e_phoff
Only when ELF_F_LAYOUT asserted
e_shoff
Only when ELF_F_LAYOUT asserted
e_flags
e_shstrndx
Member
Notes
Program Header
p_type
The application controls all
p_offset
program header entries
p_vaddr
p_paddr
p_filesz
p_memsz
p_flags
p_align
Member
Notes
Section Header
sh_name
sh_type
sh_flags
sh_addr
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
Data Descriptor
d_buf
d_type
d_size
d_off
Only when ELF_F_LAYOUT asserted
d_align
d_version
Note the program is responsible for two particularly 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 controls the data encoding used in the file.
As a special case, the value may be ELFDATANONE 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.
Consequently, 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 individual 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.
As mentioned above, the ELF_C_WRITE and ELF_C_IMPURE_WRITE
commands translate 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(ELF)
and
elf_getdata(ELF)],
the program should
reestablish the pointers after calling elf_update.
As
elf_begin(ELF)
describes, a program may ``update'' a
COFF
file to make the image consistent for
ELF.
(
COFF
is an object file format that preceded
ELF
on some computer architectures [Intel, for example].
When a program calls elf_begin on a
COFF
file, the library translates
COFF
structures to their
ELF
equivalents, allowing programs to read (but not to write) a
COFF
file as if it were
ELF.
This conversion happens only to the memory image and not to the file itself.)
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).
elf, Elf_Cmd cmd);