elf(3E) MISC. REFERENCE MANUAL PAGES 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. Pro-
grams 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 estab-
lishes an ELF descriptor for a file, it may then obtain sec-
tion 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 associ-
ated 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 descrip-
tor to reuse the input descriptor's data. That is, the
descriptors are distinct, but they could share the associ-
ated 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 architec-
tures. 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
Last change: ELF Library 1
elf(3E) MISC. REFERENCE MANUAL PAGES elf(3E)
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) m
|achines. Some library services deal
only with data objects f
|or a specific class, while others
are class-independent.| To make this distinction clear,
library function names r
|eflect their status, as described
below. |
|
DATA REPRESENTATIONS |
Conceptually, two parall
|el sets of objects support cross
compilation environment
|s. One set corresponds to file con-
tents, while the other s
|et corresponds to the native memory
image of the program|manipulating the file. Type defini-
tions 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 lo
|ss), they may be bigger if that is
more natural for the h
|ost machine. Translation facilities
exist to convert between
| file and memory representations.
Some library routines co
|nvert data automatically, while oth-
ers leave conversion |as the program's responsibility.
Either way, programs |that create object files must write
file-typed objects to th
|ose files; programs that read object
files must take a si
|milar view. See elfxlate(3E) and
elffsize(3E) for more i
|nformation. Programs may translate
data explicitly, takin
|g full control over the object file
layout and semantics. I
|f the program prefers not to have
and exercise complete| control, the library provides a
higher-level interface t
|hat hides many object file details.
elfbegin and related f
|unctions let a program deal with the
native memory types, con
|verting between memory objects and
their file equivalents a
|utomatically when reading or writing
an object file. |
|
ELF VERSIONS |
Object file versions all
|ow ELF to adapt to new requirements.
Three-independent-versio
|ns can be important to a program.
First, an application pr
|ogram knows about a particular ver-
sion by virtue of being
| compiled with certain header files.
Second, the access libra
|ry 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 versi
|ons 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
Last change: ELF Library 2
elf(3E) MISC. REFERENCE MANUAL PAGES elf(3E)
the library. Translation routines might not work prop-
erly, 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 prop-
erly, depending on whether the file has extra informa-
tion 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 sub-
sequent 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 rou-
tines directly. These routines perform no input or output,
leaving that as the application's responsibility. By assum-
ing 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
Last change: ELF Library 3
elf(3E) MISC. REFERENCE MANUAL PAGES elf(3E)
service, name, for the program.
elf32name Service names with an embedded class, 32
here, indicate they work only for the desig-
nated 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 informa-
tion.
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.
Last change: ELF Library 4
elf(3E) MISC. REFERENCE MANUAL PAGES elf(3E)
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 appropri-
ate 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 WE 32100.
#include <libelf.h>
#include <sys/elfM32.h>
Without the <sys/elfM32.h> definition, only the common ELF
information would be visible.
Last change: ELF Library 5