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 existing)
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 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.
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.
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.
Note
As mentioned above, the
ELF_C_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(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. (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).
Printable version
