elf_update(3E) 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 modi-
fied 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 descrip-
tor. 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 items 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.
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.
Page 1 Reliant UNIX 5.44 Printed 11/98
elf_update(3E) elf_update(3E)
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 pro-
poffset| gram header entries
pvaddr |
ppaddr |
Program Header pfilesz|
pmemsz |
pflags |
palign |
_________|_____________________________________
Member | Notes
______________|_________________________________
shname |
shtype |
shflags |
shaddr |
Section Header shoffset | Only when ELFFLAYOUT asserted
shsize | Only when ELFFLAYOUT asserted
shlink |
shinfo |
shaddralign| Only when ELFFLAYOUT asserted
shentsize |
_____________|_________________________________
Page 2 Reliant UNIX 5.44 Printed 11/98
elf_update(3E) elf_update(3E)
Member | Notes
___________|_________________________________
dbuf |
dtype |
Data Descriptor dsize |
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 sec-
tion header member. Although the library sets it for sections with
known types, it cannot reliably know the correct value for all sec-
tions. 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 neces-
sary, to ensure the proper alignment of each buffer.
NOTES
As mentioned above, the ELFCWRITE command translates data as neces-
sary, 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 with the
ELFCWRITE command (though ELFCNULL is allowed).
SEE ALSO
elf(3E), elfbegin(3E), elfflag(3E), elffsize(3E), elfgetdata(3E),
elfgetehdr(3E), elfgetshdr(3E), elfxlate(3E).
Page 3 Reliant UNIX 5.44 Printed 11/98