ELFUPDATE(3E) ELFUPDATE(3E)
NAME
elfupdate - update an ELF descriptor
SYNOPSIS
cc [flag ...] file ... -lelf [library ...]
#include <libelf.h>
offt elfupdate(Elf *elf, ElfCmd cmd);
DESCRIPTION
elfupdate 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.
ELFCNULL This value tells elfupdate to recalculate various
values, updating only the ELF descriptor's memory
structures. Any modified structures are flagged with the
ELFFDIRTY 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 elfbegin(3E)].
ELFCWRITE If cmd has this value, elfupdate duplicates its
ELFCNULL actions and also writes any ``dirty''
information associated with the ELF descriptor to the
file. That is, when a program has used elfgetdata or
the elfflag facilities to supply new (or update
existing) information for an ELF descriptor, those data
will be examined, coordinated, translated if necessary
[see elfxlate(3E)], and written to the file. When
portions of the file are written, any ELFFDIRTY bits
are reset, indicating those items no longer need to be
written to the file [see elfflag(3E)]. The sections'
data are 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 elfbegin, it
must have allowed writing the file. That is, the
elfbegin command must have been either ELFCRDWR or
ELFCWRITE.
If elfupdate 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.
Page 1
ELFUPDATE(3E) ELFUPDATE(3E)
When updating the internal structures, elfupdate sets some members
itself. Members listed below are the application's responsibility and
retain the values given by the program.
Member Notes
_________________________________________________________
|
eident[EIDATA] Library controls other eident values
|
etype
|
emachine
|
eversion
|
ELF Header eentry
|
ephoff Only when ELFFLAYOUT asserted
|
eshoff Only when ELFFLAYOUT asserted
|
eflags
|
eshstrndx
|
__________________|______________________________________
Member Notes
________________________________________
|
ptype The application controls all
|
poffset program header entries
|
pvaddr
|
ppaddr
|
Program Header pfilesz
|
pmemsz
|
pflags
|
palign
|
__________|_____________________________
Member Notes
_______________________________________________
|
shname
|
shtype
|
shflags
|
shaddr
|
shoffset Only when ELFFLAYOUT asserted
|
Section Header shsize Only when ELFFLAYOUT asserted
|
shlink
|
shinfo
|
shaddralign Only when ELFFLAYOUT asserted
|
shentsize
|
______________|________________________________
Page 2
ELFUPDATE(3E) ELFUPDATE(3E)
Member Notes
____________________________________________
|
dbuf
|
dtype
|
dsize
|
Data Descriptor doff Only when ELFFLAYOUT asserted
|
dalign
|
dversion
|
___________|________________________________
Note the program is responsible for two particularly important members
(among others) in the ELF header. The eversion member controls the
version of data structures written to the file. If the version is
EVNONE, the library uses its own internal version. The eident[EIDATA]
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 shentsize 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, elfupdate 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.
SEE ALSO
elf(3E),
elfbegin(3E),
elfflag(3E),
elffsize(3E),
elfgetdata(3E),
elfgetehdr(3E), elfgetshdr(3E), elfxlate(3E).
NOTE
As mentioned above, the ELFCWRITE 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 elfgetehdr(3E)
and elfgetdata(3E)], the program should reestablish the pointers after
calling elfupdate.
Page 3