elf man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

elf(3ELF)		     ELF Library Functions		     elf(3ELF)

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 (Exe‐
       cutable 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,
       elf_begin(3ELF) 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 pro‐
       gram  establishes an ELF descriptor for a file, it may then obtain sec‐
       tion  descriptors  to  manipulate  the  sections	 of  the   file	  (see
       elf_getscn(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 particular ELF descriptor, just as a sec‐
       tion 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  buf‐
       fers 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 architectures. An important distinc‐
       tion  among  object  files  is the class, or capacity, of the file. The
       32-bit class supports architectures in which a 32-bit object can repre‐
       sent addresses, file sizes, and so on, 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	   │
       └─────────────────────────────┴─────────────────────────────┘

       The  64−bit  class  works the same as the 32−bit class, substituting 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-indepen‐
       dent.  To  make	this distinction 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 contents, 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 repre‐
       sentations. 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 elf32_xlatetof(3ELF) and elf32_fsize(3ELF) 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 applica‐
       tion program knows about a particular version by virtue of  being  com‐
       piled  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, deter‐
       mined 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 prob‐
       lems 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(3ELF)
       to pass its version to the library, thus establishing the working  ver‐
       sion  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(3ELF)  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 elf32_xlatetom(3ELF) or elf32_xlatetof(3ELF)
       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, indi‐
			 cate they work	 only  for  the	 designated  class  of
			 files.

       Elf_Type		 Data  types can be class-independent as well, distin‐
			 guished 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 enu‐
			 meration; 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
			 elf32_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 elf32_xlatetom()  or
			 elf32_xlatetof(), deals with multiple types, names of
			 this form specify the desired TYPE. Thus,  for	 exam‐
			 ple,  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.

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		     <fcntl.h>
	 #include		     <stdio.h>
	 #include		     <libelf.h>
	 #include		     <stdlib.h>
	 #include		     <string.h>
	 static void failure(void);
	 void
	 main(int argc, char ** argv)
	 {
	     Elf32_Shdr *    shdr;
	     Elf32_Ehdr *    ehdr;
	     Elf *	  elf;
	     Elf_Scn *	  scn;
	     Elf_Data *	   data;
	     int	fd;
	     unsigned int    cnt;

		  /* Open the input file */
	     if ((fd = open(argv[1], O_RDONLY)) == -1)
		 exit(1);

		 /* Obtain the ELF descriptor */
	     (void) elf_version(EV_CURRENT);
	     if ((elf = elf_begin(fd, ELF_C_READ, NULL)) == NULL)
		 failure();

		 /* Obtain the .shstrtab data buffer */
	     if (((ehdr = elf32_getehdr(elf)) == NULL) ||
		 ((scn = elf_getscn(elf, ehdr->e_shstrndx)) == NULL) ||
		 ((data = elf_getdata(scn, NULL)) == NULL))
		 failure();

		 /* Traverse input filename, printing each section */
	     for (cnt = 1, scn = NULL; scn = elf_nextscn(elf, scn); cnt++) {
		 if ((shdr = elf32_getshdr(scn)) == NULL)
		     failure();
	     (void) printf("[%d]    %s\n", cnt,
		 (char *)data->d_buf + shdr->sh_name);
	     }
	 }	  /* end main */

	 static void
	 failure()
	 {
	     (void) fprintf(stderr, "%s\n", elf_errmsg(elf_errno()));
	     exit(1);
	 }

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Committed			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       ar.h(3HEAD),   elf32_checksum(3ELF),   elf32_fsize(3ELF),    elf32_get‐
       shdr(3ELF),   elf32_xlatetof(3ELF),   elf_begin(3ELF),  elf_cntl(3ELF),
       elf_errmsg(3ELF),	  elf_fill(3ELF),	   elf_getarhdr(3ELF),
       elf_getarsym(3ELF),   elf_getbase(3ELF),	 elf_getdata(3ELF),  elf_geti‐
       dent(3ELF), elf_getscn(3ELF), elf_hash(3ELF), elf_kind(3ELF),  elf_mem‐
       ory(3ELF),   elf_rawfile(3ELF),	 elf_strptr(3ELF),   elf_update(3ELF),
       elf_version(3ELF),  gelf(3ELF),	libelf(3LIB),  attributes(5),	lfcom‐
       pile(5)

       ANSI C Programmer's Guide

   SPARC only
       a.out(4)

NOTES
       Information  in the ELF headers is separated into common parts and pro‐
       cessor-specific parts. A program can  make  a  processor's  information
       available  by  including the appropriate header: <sys/elf_NAME.h> where
       NAME matches the processor 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 based system.

	 #include <libelf.h>
	 #include <sys/elf_SPARC.h>

       Without	the <sys/elf_SPARC.h> definition, only the common ELF informa‐
       tion would be visible.

       A program could use the following code to  ``see''  the	processor-spe‐
       cific information for the Intel 80386:

	 #include <libelf.h>
	 #include <sys/elf_386.h>

       Without the <sys/elf_386.h> definition, only the common ELF information
       would be visible.

       Although reading the objects is rather straightforward,	writing/updat‐
       ing  them can corrupt the shared offsets among sections. Upon creation,
       relationships are established among the sections	 that  must  be	 main‐
       tained even if the object's size is changed.

SunOS 5.11			  23 Jul 2001			     elf(3ELF)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net