elf(3E)

object file access library

From the original Amiga UNIX 2.1 manual. Some things it mentions may not be in this release.

NAME · SYNOPSIS · DESCRIPTION · FILE CLASSES · SYSTEM SERVICES · SEE ALSO · NOTES

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.

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
               _______________________________________
               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 con-
     tents, while the other set 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 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 oth-
     ers  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  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  ver-
     sion  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 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 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.

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 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 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.

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.

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/elf_NAME.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/elf_M32.h>
Without the <sys/elf_M32.h> definition, only the common  ELF
information would be visible.