elf(3E) SDK R4.11 elf(3E)
NAME
elf - object file access library
SYNOPSIS
cc [flag ...] file ... -lelf [library ...]
#include <libelf.h>
DESCRIPTION
Functions in the ELF access library let a program manipulate ELF
(Executable and Linking Format) object files, archive files, and
archive members. The header file provides type and function
declarations for all library services.
Programs communicate with many of the higher-level routines using an
ELF descriptor. That is, when the program starts working with a
file, elfbegin creates an ELF descriptor through which the program
manipulates the structures and information in the file. These ELF
descriptors can be used both to read and to write files. After the
program establishes an ELF descriptor for a file, it may then obtain
section descriptors to manipulate the sections of the file [see
elfgetscn(3E)]. Sections hold the bulk of an object file's real
information, such as text, data, the symbol table, and so on. A
section descriptor ``belongs'' to a particular ELF descriptor, just
as a section belongs to a file. Finally, data descriptors are
available through section descriptors, allowing the program to
manipulate the information associated with a section. A data
descriptor ``belongs'' to a section descriptor.
Descriptors provide private handles to a file and its pieces. In
other words, a data descriptor is associated with one section
descriptor, which is associated with one ELF descriptor, which is
associated with one file. Although descriptors are private, they
give access to data that may be shared. Consider programs that
combine input files, using incoming data to create or update another
file. Such a program might get data descriptors for an input and an
output section. It then could update the output descriptor to reuse
the input descriptor's data. That is, the descriptors are distinct,
but they could share the associated data bytes. This sharing avoids
the space overhead for duplicate buffers and the performance overhead
for copying data unnecessarily.
File Classes
ELF provides a framework in which to define a family of object files,
supporting multiple processors and architectures. An important
distinction among object files is the class, or capacity, of the
file. The 32-bit class supports architectures in which a 32-bit
object can represent addresses, file sizes, etc., as in the
following.
Name Purpose
--------------+-------------------------
Elf32Addr | Unsigned address
Elf32Half | Unsigned medium integer
Elf32Off | Unsigned file offset
Elf32Sword | Signed large integer
Elf32Word | Unsigned large integer
unsigned char | Unsigned small integer
--------------+-------------------------
Other classes will be defined as necessary, to support larger (or
smaller) machines. Some library services deal only with data objects
for a specific class, while others are class-independent. To make
this distinction clear, library function names reflect their status,
as described below.
Data Representations
Conceptually, two parallel sets of objects support cross compilation
environments. One set corresponds to file contents, while the other
set corresponds to the native memory image of the program
manipulating the file. Type definitions supplied by the header files
work on the native machine, which may have different data encodings
(size, byte order, etc.) than the target machine. Although native
memory objects should be at least as big as the file objects (to
avoid information loss), they may be bigger if that is more natural
for the host machine.
Translation facilities exist to convert between file and memory
representations. Some library routines convert data automatically,
while others leave conversion as the program's responsibility.
Either way, programs that create object files must write file-typed
objects to those files; programs that read object files must take a
similar view. See elfxlate(3E) and elffsize(3E) for more
information.
Programs may translate data explicitly, taking full control over the
object file layout and semantics. If the program prefers not to have
and exercise complete control, the library provides a higher-level
interface that hides many object file details. elfbegin and related
functions let a program deal with the native memory types, converting
between memory objects and their file equivalents automatically when
reading or writing an object file.
Elf Versions
Object file versions allow ELF to adapt to new requirements. Three--
independent--versions can be important to a program. First, an
application program knows about a particular version by virtue of
being compiled with certain header files. Second, the access library
similarly is compiled with header files that control what versions it
understands. Third, an ELF object file holds a value identifying its
version, determined by the ELF version known by the file's creator.
Ideally, all three versions would be the same, but they may differ.
If a program's version is newer than the access library, the
program might use information unknown to the library.
Translation routines might not work properly, leading to
undefined behavior. This condition merits installing a new
library.
The library's version might be newer than the program's and the
file's. The library understands old versions, thus avoiding
compatibility problems in this case.
Finally, a file's version might be newer than either the program
or the library understands. The program might or might not be
able to process the file properly, depending on whether the file
has extra information and whether that information can be safely
ignored. Again, the safe alternative is to install a new
library that understands the file's version.
To accommodate these differences, a program must use elfversion to
pass its version to the library, thus establishing the working
version for the process. Using this, the library accepts data from
and presents data to the program in the proper representations. When
the library reads object files, it uses each file's version to
interpret the data. When writing files or converting memory types to
the file equivalents, the library uses the program's working version
for the file data.
System Services
As mentioned above, elfbegin and related routines provide a higher-
level interface to ELF files, performing input and output on behalf
of the application program. These routines assume a program can hold
entire files in memory, without explicitly using temporary files.
When reading a file, the library routines bring the data into memory
and perform subsequent operations on the memory copy. Programs that
wish to read or write large object files with this model must execute
on a machine with a large process virtual address space. If the
underlying operating system limits the number of open files, a
program can use elfcntl to retrieve all necessary data from the
file, allowing the program to close the file descriptor and reuse it.
Although the elfbegin interfaces are convenient and efficient for
many programs, they might be inappropriate for some. In those cases,
an application may invoke the elfxlate data translation routines
directly. These routines perform no input or output, leaving that as
the application's responsibility. By assuming a larger share of the
job, an application controls its input and output model.
Library Names
Names associated with the library take several forms.
elfname These class-independent names perform some service,
name, for the program.
elf32name Service names with an embedded class, 32 here,
indicate they work only for the designated class of
files.
ElfType Data types can be class-independent as well,
distinguished by Type.
Elf32Type Class-dependent data types have an embedded class
name, 32 here.
ELFCCMD Several functions take commands that control their
actions. These values are members of the ElfCmd
enumeration; they range from zero through
ELFCNUM-1.
ELFFFLAG Several functions take flags that control library
status and/or actions. Flags are bits that may be
combined.
ELF32FSZTYPE These constants give the file sizes in bytes of the
basic ELF types for the 32-bit class of files. See
elffsize for more information.
ELFKKIND The function elfkind identifies the KIND of file
associated with an ELF descriptor. These values are
members of the ElfKind enumeration; they range from
zero through ELFKNUM-1.
ELFTTYPE When a service function, such as elfxlate, deals
with multiple types, names of this form specify the
desired TYPE. Thus, for example, ELFTEHDR is
directly related to Elf32Ehdr. These values are
members of the ElfType enumeration; they range from
zero through ELFTNUM-1.
SEE ALSO
cof2elf(1), elfbegin(3E), elfcntl(3E), elfend(3E), elferror(3E),
elffill(3E), elfflag(3E), elffsize(3E), elfgetarhdr(3E),
elfgetarsym(3E), elfgetbase(3E), elfgetdata(3E), elfgetehdr(3E),
elfgetident(3E), elfgetphdr(3E), elfgetscn(3E), elfgetshdr(3E),
elfhash(3E), elfkind(3E), elfnext(3E), elfrand(3E),
elfrawfile(3E), elfstrptr(3E), elfupdate(3E), elfversion(3E),
elfxlate(3E), a.out(4) ar(4)
The ``Object Files'' chapterin the Programmer's Guide: ANSI C and
Programming Support Tools.
NOTES
Information in the ELF header files is separated into common parts
and processor-specific parts. A program can make a processor's
information available by including the appropriate header file:
<sys/elfNAME.h> where NAME matches the processor name as used in the
ELF file header.
Symbol Processor
-------+----------------
M32 | AT&T WE 32100
SPARC | SPARC
386 | Intel 80386
486 | Intel 80486
860 | Intel 80860
68K | Motorola 68000
88K | Motorola 88000
-------+----------------
Other processors will be added to the table as necessary. To
illustrate, a program could use the following code to ``see'' the
processor-specific information for the Motorola 88000:
#include <libelf.h>
#include <sys/elf88K.h>
Without the <sys/elf88K.h> definition, only the common ELF
information would be visible.
Licensed material--property of copyright holder(s)