DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

elf(S)


elf -- object file access library

Syntax

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(S) creates a 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 can obtain section descriptors to manipulate the sections of the file (see elf_getscn(S)). 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 might 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 space overhead for duplicate buffers and 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, 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

 +--------------+-------------------------+
 |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 might have different data encodings (size, byte order, and so forth) than the target machine. Native memory objects should be at least as big as the file objects (to avoid information loss), but they can 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. For more information, see elf_xlate(S) and elf_fsize(S).

Programs can translate data explicitly, taking full control over the object file layout and semantics. If the programmer prefers not to exercise complete control, the library 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:

Ideally, all three versions would be the same, but they can differ, and that can present problems:

To accommodate these differences, a program must use elf_version(S) to pass its version to the library, thus establishing the "working version" for the process. Using the working version, the library represents data properly when transferring it to and from the program. 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, elf_begin( ) and related routines provide a higher-level interface to ELF files, handling input and output on behalf of the application program. These routines assume that 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 do subsequent operations on the memory copy.

Programs that read or write large object files with this model must run 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(S) 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. If not, an application can invoke the elf_xlate( ) data translation routines directly. These routines do no input or output, leaving that as the application's responsibility. By assuming a larger share of the job, an application controls its own input and output model.

Library names

Names associated with the library take several forms.

elf_name
These class-independent names do some service, name, for the program.

elf32_name
Service names with an embedded class, 32 here, indicate that 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.

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(S) 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(S). These values are members of the Elf_Type enumeration; they range from zero through ELF_T_NUM-1.

Diagnostics

Error conditions are identified through the routine elf_error(S).

See also

a.out(FP), ar(FP), cof2elf(CP), elf_begin(S), elf_cntl(S), elf_end(S), elf_error(S), elf_fill(S), elf_flag(S), elf_fsize(S), elf_getarhdr(S), elf_getarsym(S), elf_getbase(S), elf_getdata(S), elf_getehdr(S), elf_getident(S), elf_getphdr(S), elf_getscn(S), elf_getshdr(S), elf_hash(S), elf_kind(S), elf_next(S), elf_rand(S), elf_rawfile(S), elf_strptr(S), elf_update(S), elf_version(S), elf_xlate(S), ``ELF object files'' in Developer's Topics

Standards conformance

elf(S) is not part of any currently supported standard; it was developed by UNIX System Laboratories, Inc. and is maintained by The SCO Group.
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003