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

FreeBSD Manual Pages


home | help
elf(3E)								       elf(3E)

       elf - object file access	library

       [flag...	] file...  [library] ...

       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 file provides type and function declarations for
       all library services.

       Programs	communicate with many of the higher-level  routines  using  an
       That  is,  when	the program starts working with	a file,	creates	an ELF
       descriptor through which	the program manipulates	the structures and in-
       formation  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 ta-
       ble, and	so on.	A section descriptor ``belongs'' to a  particular  ELF
       descriptor,  just  as  a	 section belongs to a file.  Finally, data de-
       scriptors are available through section descriptors, allowing the  pro-
       gram  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 associ-
       ated  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 architectures.  An	important dis-
       tinction	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

       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 may have different	data encodings (size, byte or-
       der, and	so forth) than the target machine.  Although native memory ob-
       jects should be at least	as big as the file objects (to avoid  informa-
       tion loss), they	may be bigger if that is more natural for the host ma-

       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 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 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  applica-
       tion  program  knows about a particular version by virtue of being com-
       piled with certain header files.	 Second, the access library  similarly
       is  compiled  with  header  files  that control what versions it	under-
       stands.	Third, an ELF object file holds	a value	identifying  its  ver-
       sion,  determined by the	ELF version known by the file's	creator.  Ide-
       ally, 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

       To accommodate these differences, a program must	use to pass  its  ver-
       sion  to	 the  library,	thus  establishing the 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, and related routines	provide	a higher-level	inter-
       face  to	ELF files, performing input and	output on behalf of the	appli-
       cation 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 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 sys-
       tem limits the number of	open files, a program can use to retrieve  all
       necessary  data	from  the file,	allowing the program to	close the file
       descriptor and reuse it.

       Although	the interfaces are convenient and efficient for	many programs,
       they  might  be inappropriate for some.	In those cases,	an application
       may invoke the data translation routines	directly.  These routines per-
       form no input or	output,	leaving	that as	the application's responsibil-
       ity.  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.

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

	      Service names with an embedded class,
				here,indicate  they  work  only	for the	desig-
				nated class of files.

	      Service names with an embedded class,
				here,indicate they work	only  for  the	desig-
				nated class of files.

	      Data types can be	class-independent as well, distinguished by

	      Class-dependent data types have an embedded class	name,

	      Class-dependent data types have an embedded class	name,

	      Several functions	take commands that control their actions.
				These  values  are members of the enumeration;
				they range from	zero through

	      Several functions	take flags that	control
				library	status and/or actions.	Flags are bits
				that may be combined.

	      These constants give the file sizes in bytes
				of the basic ELF types for the 32-bit class of
				files.	See for	more information.

	      These constants give the file sizes in bytes
				of the basic ELF types for the 64-bit class of
				files.	See for	more information.

	      The function	identifies the KIND of file associated with an
				ELF descriptor.	 These values are  members  of
				the enumeration; they range from zero through

	      When a service function, such as
				deals  with multiple types, names of this form
				specify	the desired TYPE.  Thus, for  example,
				is  directly  related to These values are mem-
				bers of	the enumeration; they range from  zero

       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 appropriate header file: where NAME matches
       the processor name as used in the ELF file header.

				 Symbol	  Processor
				 parisc	  PA RISC

       Other processors	will be	added to the table as  necessary.   To	illus-
       trate, a	program	could use the following	code to	``see''	the processor-
       specific	information for	the WE 32100.

       Without the definition, only the	common ELF information would be	 visi-

       a.out(4),  ar(4),  elf_begin(3E),  elf_cntl(3E),	 elf_end(3E),  elf_er-
       ror(3E),	elf_fill(3E), elf_flag(3E),  elf_fsize(3E),  elf_getarhdr(3E),
       elf_getarsym(3E),  elf_getbase(3E),  elf_getdata(3E),  elf_getehdr(3E),
       elf_getident(3E),  elf_getphdr(3E),  elf_getscn(3E),   elf_getshdr(3E),
       elf_hash(3E),   elf_kind(3E),   elf_next(3E),   elf_rand(3E),  elf_raw-
       file(3E),     elf_strptr(3E),	 elf_update(3E),      elf_version(3E),



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

home | help