elf(3E) 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, elf_begin 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 elf_getscn(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.
Copyright 1994 Novell, Inc. Page 1
elf(3E) elf(3E)
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, and so forth, as in the following.
Name Purpose
_____________|_________________________
Elf32_Addr | Unsigned address
Elf32_Half | Unsigned medium integer
Elf32_Off | Unsigned file offset
Elf32_Sword | Signed large integer
Elf32_Word | 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, and so
forth) 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 elf_xlate(3E)
and elf_fsize(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
Copyright 1994 Novell, Inc. Page 2
elf(3E) elf(3E)
provides a higher-level interface that hides many object file
details. elf_begin 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
elf_version 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.
Copyright 1994 Novell, Inc. Page 3
elf(3E) elf(3E)
System Services
As mentioned above, elf_begin 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 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 elf_cntl to retrieve all necessary data from
the file, allowing the program to close the file descriptor
and reuse it.
Although the elf_begin interfaces are convenient and efficient
for many programs, they might be inappropriate for some. In
those cases, an application may invoke the elf_xlate 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.
elf_name These class-independent names perform some
service, name, for the program.
elf32_name Service names with an embedded class, 32 here,
indicate they work only for the designated
class of files.
Elf_Type Data types can be class-independent as well,
distinguished by Type.
Elf32_Type Class-dependent data types have an embedded
class name, 32 here.
ELF_C_CMD Several functions take commands that control
their actions. These values are members of
the Elf_Cmd enumeration; they range from zero
through ELF_C_NUM-1.
Copyright 1994 Novell, Inc. Page 4
elf(3E) elf(3E)
ELF_F_FLAG Several functions take flags that control
library status and/or actions. Flags are bits
that may be combined.
ELF32_FSZ_TYPE These constants give the file sizes in bytes
of the basic ELF types for the 32-bit class of
files. See elf_fsize for more information.
ELF_K_KIND The function elf_kind identifies the KIND of
file associated with an ELF descriptor. These
values are members of the Elf_Kind
enumeration; they range from zero through
ELF_K_NUM-1.
ELF_T_TYPE When a service function, such as elf_xlate,
deals with multiple types, names of this form
specify the desired TYPE. Thus, for example,
ELF_T_EHDR is directly related to Elf32_Ehdr.
These values are members of the Elf_Type
enumeration; they range from zero through
ELF_T_NUM-1.
REFERENCES
a.out(4), ar(4), cof2elf(1), elf_begin(3E), elf_cntl(3E),
elf_end(3E), elf_error(3E), elf_fill(3E), elf_flag(3E),
elf_fsize(3E), elf_getarhdr(3E), elf_getarsym(3E),
elf_getbase(3E), elf_getdata(3E), elf_getehdr(3E),
elf_getident(3E), elf_getphdr(3E), elf_getscn(3E),
elf_getshdr(3E), elf_hash(3E), elf_kind(3E), elf_next(3E),
elf_rand(3E), elf_rawfile(3E), elf_strptr(3E), elf_update(3E),
elf_version(3E), elf_xlate(3E)
NOTICES
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/elf_NAME.h where NAME matches the processor
name as used in the ELF file header.
Copyright 1994 Novell, Inc. Page 5
elf(3E) 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/elf_M32.h>
Without the sys/elf_M32.h definition, only the common ELF
information would be visible.
Copyright 1994 Novell, Inc. Page 6