Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
elf(3ELF)		     ELF Library Functions		     elf(3ELF)

       elf - object file access	library

       cc [ flag ... ] file ...	-lelf [	library	... ]
       #include	<libelf.h>

       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 li-
       brary 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 ma-
       nipulates  the  structures  and	information in the file. These ELF de-
       scriptors 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 in-
       formation, 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

       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 ma-
       chine, 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  in-
       terface	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  in-
       dependent versions can be important to a	program. First,	an application
       program knows about a particular	version	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  ver-
       sions 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 al-
       ternative is to install a new library that understands the file's  ver-

       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  en-
       tire  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  ma-
       chine with a large process virtual address space. If the	underlying op-
       erating 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

   Library Names
       Names associated	with the library take several forms.

       elf_name		       These class-independent names perform some ser-
			       vice, 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  li-
			       brary  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_xlate-
			       tom() or	elf32_xlatetof(), deals	with  multiple
			       types,  names  of this form specify the desired
			       TYPE.  Thus, for	 example,  ELF_T_EHDR  is  di-
			       rectly  related to Elf32_Ehdr. These values are
			       members of the Elf_Type enumeration; they range
			       from zero through ELF_T_NUM-1.

       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);
       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)

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

	       /* 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))

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

       static void
	   (void) fprintf(stderr, "%s\n", elf_errmsg(elf_errno()));

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

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Stable			   |
       |MT-Level		     |MT-Safe			   |

       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-

       ANSI C Programmer's Guide

   SPARC only

       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.10			  23 Jul 2001			     elf(3ELF)


Want to link to this manual page? Use this URL:

home | help