elf_update(3E) (ELF Library) elf_update(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.
8/91 Page 1
elf_update(3E) (ELF Library) elf_update(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 8/91
elf_update(3E) (ELF Library) elf_update(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.
As elfbegin(3E) describes, a program may ``update'' a COFF file to
make the image consistent for ELF . The ELFCNULL command updates
only the memory image; one can use the ELFCWRITE 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
8/91 Page 3
elf_update(3E) (ELF Library) elf_update(3E)
with the ELFCWRITE command (though ELFCNULL is allowed).
Page 4 8/91