elf(3E) UNIX System V(ELF Library) 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.
10/89 Page 1
elf(3E) UNIX System V(ELF Library) elf(3E)
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.
Page 2 10/89
elf(3E) UNIX System V(ELF Library) elf(3E)
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.
10/89 Page 3
elf(3E) UNIX System V(ELF Library) elf(3E)
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'' in the chapter 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.
Page 4 10/89
elf(3E) UNIX System V(ELF Library) elf(3E)
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 WE 32100.
#include <libelf.h>
#include <sys/elfM32.h>
Without the <sys/elfM32.h> definition, only the common ELF information
would be visible.
10/89 Page 5