ELF Library Functions elf(3ELF)
NAME
elf - object file access library
SYNOPSIS
cc [ flag ... ] file ... -lelf [ library ... ]
#include
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 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(3ELF) creates an ELF descrip-
tor 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(3ELF)). 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 par-
ticular ELF descriptor, just as a section belongs to a file.
Finally, data descriptors are available through section
descriptors, allowing the program to manipulate the informa-
tion 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 pro-
gram 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 architec-
tures. An important distinction among object files is the
class, or capacity, of the file. The 32-bit class supports
SunOS 5.11 Last change: 23 Jul 2001 1
ELF Library Functions elf(3ELF)
architectures in which a 32-bit object can represent
addresses, file sizes, and so on, 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
The 64-bit class works the same as the 32-bit class, substi-
tuting 64 for 32 as necessary. 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 dis-
tinction clear, library function names reflect their status,
as described below.
Data Representation
Conceptually, two parallel sets of objects support cross
compilation environments. One set corresponds to file con-
tents, while the other set corresponds to the native memory
image of the program manipulating the file. Type definitions
supplied by the headers work on the native machine, which
may have different data encodings (size, byte order, and so
on) 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 elf32xlatetof(3ELF) and elf32fsize(3ELF) for more
information.
SunOS 5.11 Last change: 23 Jul 2001 2
ELF Library Functions elf(3ELF)
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 automati-
cally 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 ver-
sion by virtue of being compiled with certain headers.
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. Trans-
lation routines might not work properly, leading to unde-
fined 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 alterna-
tive is to install a new library that understands the file's
version.
To accommodate these differences, a program must use
elfversion(3ELF) 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.
SunOS 5.11 Last change: 23 Jul 2001 3
ELF Library Functions elf(3ELF)
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 exe-
cute 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(3ELF) 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 effi-
cient for many programs, they might be inappropriate for
some. In those cases, an application may invoke the
elf32xlatetom(3ELF) or elf32xlatetof(3ELF) data transla-
tion 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 embed-
ded class name, 32 here.
ELFCMD Several functions take commands that con-
trol their actions. These values are
members of the ElfCmd enumeration; they
range from zero through ELFCNUM-1.
SunOS 5.11 Last change: 23 Jul 2001 4
ELF Library Functions elf(3ELF)
ELFLAG 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 elf32fsize() for
more information.
ELFKIND 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.
ELFTYPE When a service function, such as
elf32xlatetom() or elf32xlatetof(),
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.
EXAMPLES
Example 1 An interpretation of elf file.
The basic interpretation of an ELF file consists of:
o opening an ELF object file
o obtaining an ELF descriptor
o analyzing the file using the descriptor.
The following example opens the file, obtains the ELF
descriptor, and prints out the names of each section in the
file.
#include
#include
#include
#include
#include
SunOS 5.11 Last change: 23 Jul 2001 5
ELF Library Functions elf(3ELF)
static void failure(void);
void
main(int argc, char ** argv)
{
Elf32Shdr * shdr;
Elf32Ehdr * ehdr;
Elf * elf;
ElfScn * scn;
ElfData * data;
int fd;
unsigned int cnt;
/* Open the input file */
if ((fd = open(argv[1], ORDONLY)) == -1)
exit(1);
/* Obtain the ELF descriptor */
(void) elfversion(EVCURENT);
if ((elf = elfbegin(fd, ELFCREAD, NUL)) == NUL)
failure();
/* Obtain the .shstrtab data buffer */
if (((ehdr = elf32getehdr(elf)) == NUL)
((scn = elfgetscn(elf, ehdr->eshstrndx)) == NUL)
((data = elfgetdata(scn, NUL)) == NUL))
failure();
/* Traverse input filename, printing each section */
for (cnt = 1, scn = NUL; scn = elfnextscn(elf, scn); cnt]) {
if ((shdr = elf32getshdr(scn)) == NUL)
failure();
(void) printf("[%d] %s\n", cnt,
(char *)data->dbuf ] shdr->shname);
}
} /* end main */
static void
failure()
{
(void) fprintf(stderr, "%s\n", elferrmsg(elferrno()));
exit(1);
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 23 Jul 2001 6
ELF Library Functions elf(3ELF)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Stable
MT-Level MT-Safe
SEE ALSO
ar.h(3HEAD), elf32checksum(3ELF), elf32fsize(3ELF),
elf32getshdr(3ELF), elf32xlatetof(3ELF), elfbegin(3ELF),
elfcntl(3ELF), elferrmsg(3ELF), elffill(3ELF),
elfgetarhdr(3ELF), elfgetarsym(3ELF), elfgetbase(3ELF),
elfgetdata(3ELF), elfgetident(3ELF), elfgetscn(3ELF),
elfhash(3ELF), elfkind(3ELF), elfmemory(3ELF),
elfrawfile(3ELF), elfstrptr(3ELF), elfupdate(3ELF),
elfversion(3ELF), gelf(3ELF), libelf(3LIB), attributes(5),
lfcompile(5)
ANSI C Programmer's Guide
SPARC only
a.out(4)
NOTES
Information in the ELF headers is separated into common
parts and processor-specific parts. A program can make a
processor's information available by including the appropri-
ate header: where NAME matches the proces-
sor name as used in the ELF file header.
Name Processor
M32 AT&T WE 32100
SPARC SPARC
386 Intel 80386, 80486, Pentium
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 SPARC
SunOS 5.11 Last change: 23 Jul 2001 7
ELF Library Functions elf(3ELF)
based system.
#include
#include
Without the definition, only the common
ELF information would be visible.
A program could use the following code to ``see'' the
processor-specific information for the Intel 80386:
#include
#include
Without the definition, only the common ELF
information would be visible.
Although reading the objects is rather straightforward,
writing/updating them can corrupt the shared offsets among
sections. Upon creation, relationships are established among
the sections that must be maintained even if the object's
size is changed.
SunOS 5.11 Last change: 23 Jul 2001 8
|
