elf_update(3E) elf_update(3E)
NAME
elf_update - update an ELF descriptor
SYNOPSIS
cc [flag . . . ] file . . . -lelf [library] . . .
#include <libelf.h>
off_t elf_update(Elf *elf, Elf_Cmd cmd);
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.
Copyright 1994 Novell, Inc. Page 1
elf_update(3E) elf_update(3E)
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
_________________|_______________________________________
e_ident[EI_DATA]| Library controls other e_ident values
e_type |
e_machine |
e_version |
ELF Header e_entry |
e_phoff | Only when ELF_F_LAYOUT asserted
e_shoff | Only when ELF_F_LAYOUT asserted
e_flags |
e_shstrndx |
_________________|_______________________________________
Copyright 1994 Novell, Inc. Page 2
elf_update(3E) elf_update(3E)
Member Notes
_________|______________________________
p_type | The application controls all
p_offset| program header entries
p_vaddr |
p_paddr |
Program Header p_filesz|
p_memsz |
p_flags |
p_align |
_________|______________________________
Member Notes
_____________|_________________________________
sh_name |
sh_type |
sh_flags |
sh_addr |
sh_offset | Only when ELF_F_LAYOUT asserted
Section Header sh_size | Only when ELF_F_LAYOUT asserted
sh_link |
sh_info |
sh_addralign| Only when ELF_F_LAYOUT asserted
sh_entsize |
_____________|_________________________________
Member Notes
__________|_________________________________
d_buf |
d_type |
d_size |
Data Descriptor 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.
Copyright 1994 Novell, Inc. Page 3
elf_update(3E) elf_update(3E)
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.
REFERENCES
elf(3E), elf_begin(3E), elf_flag(3E), elf_fsize(3E),
elf_getdata(3E), elf_getehdr(3E), elf_getshdr(3E),
elf_xlate(3E)
NOTICES
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(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).
Copyright 1994 Novell, Inc. Page 4