[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1


elf_update Subroutine

Purpose

Update an ELF descriptor

Library

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

Syntax


off_t elf_update(Elf * elf, Elf_Cmd cmd);

Description

elf_update causes the library to examine the information associated with an ELF descriptor, elf, and to recalculate the structural data needed to generate the file's image.

The ELF_C_WRITE and ELF_C_IMPURE_WRITE (shown below) commands translate data as necessary, before writing them to the file. This translation is not always transparent to the application program. If a program has obtained pointers to data associated with a file [for example, see the elf32_getehdr and elf_getdata subroutines], the program should reestablish the pointers after calling elf_update.

As elf_begin describes, a program may update a COFF file to make the image consistent for ELF. (COFF is an object file format that preceded ELF on some computer architectures [Intel, for example]). When a program calls elf_begin on a COFF file, the library translates COFF structures to their ELF equivalents, allowing programs to read (but not to write) a COFF file as if it were ELF. This conversion happens only to the memory image and not to the file itself. The ELF_C_NULL command updates only the memory image; you can use the ELF_C_WRITE command to modify the file as well. Absolute executable files (a.out files) require special alignment, which cannot normally be preserved between COFF and ELF. Consequently, you cannot update an executable COFF file with the ELF_C_WRITE command (though ELF_C_NULL is allowed).

Parameters


cmd Specifies the action to take and can be set to any of the following values.

ELF_C_NULL
Specifies that various values must be recalculate, updating only the ELF descriptor's memory structures. Any modified structures are flagged with the ELF_F_DIRTY bit. A program thus can update the structural information and then reexamine them without changing the file associated with the ELF descriptor. Because this does not change the file, the ELF descriptor may allow reading, writing, or both reading and writing [see the elf_begin subroutine].

ELF_C_WRITE
Specifies the same as ELF_C_NULL but also writes any dirty information associated with the ELF descriptor to the file. That is, when a program has used elf_getdata or the elf_flagdata facilities to supply new (or update existing) information for an ELF descriptor, those data will be examined, coordinated, translated if necessary [see the elf32_xlatetof subroutine], and written to the file. When portions of the file are written, any ELF_F_DIRTY bits are reset, indicating those items no longer need to be written to the file [see the elf_flagdata subroutine]. The sections' data is written in the order of their section header entries, and the section header table is written to the end of the file.

When the ELF descriptor was created with elf_begin, it must have allowed writing the file. That is, the elf_begin command must have been either ELF_C_RDWR or ELF_C_WRITE.

ELF_C_IMPURE_WRITE
Attempts to write an image of the entire output file in memory either by allocating storage from the heap or by mapping an image of the output file. This allocation, and the elf_update call, can fail if there is insufficient memory to hold the entire file (or even the largest sections' data after translation). If ELF_C_IMPURE_WRITE is used instead, elf_update will, if necessary, perform in place the memory-to-file translation in an attempt to use the least amount of extra memory. Thus, ELF_C_IMPURE_WRITE should only be used when the data will not be examined after the call to elf_update.

When updating the internal structures, elf_update sets some members itself. Members listed below are the application's responsibility and retain the values given by the program.


  Member Notes
ELF Header e_ident[EI_DATA] Library controls other e_ident values
  e_type  
  e_machine  
  e_version  
  e_entry  
  e_phoff Only when ELF_F_LAYOUT asserted
  e_shoff Only when ELF_F_LAYOUT asserted
  e_flags  
  e_shstrndx  
 
  Member Notes
Program Header p_type The application controls all
  p_offset program header entries
  p_vaddr  
  p_paddr  
  p_filesz  
  p_memsz  
  p_flags  
  p_align  
 
  Member Notes
Section Header sh_name  
  sh_type  
  sh_flags  
  sh_addr  
  sh_offset Only when ELF_F_LAYOUT asserted
  sh_size Only when ELF_F_LAYOUT asserted
  sh_link  
  sh_info  
  sh_addralign Only when ELF_F_LAYOUT asserted
  sh_entsize  
 
  Member Notes
Data Descriptor d_buf  
  d_type  
  d_size  
  d_off Only when ELF_F_LAYOUT asserted
  d_align  
  d_version  

The program is responsible for two particularly important members (among others) in the ELF header. The e_version member controls the version of data structures written to the file. If the version is EV_NONE, the library uses its own internal version. The e_ident[EI_DATA] entry controls the data encoding used in the file. As a special case, the value may be ELFDATANONE to request the native data encoding for the host machine. An error occurs in this case if the native encoding does not match a file encoding known by the library.

Further note that the program is responsible for the sh_entsize section header member. Although the library sets it for sections with known types, it cannot reliably know the correct value for all sections. Consequently, the library relies on the program to provide the values for unknown section type. If the entry size is unknown or not applicable, the value should be set to zero.

When deciding how to build the output file, elf_update obeys the alignments of individual data buffers to create output sections. A sections most strictly aligned data buffer controls the sections alignment. The library also inserts padding between buffers, as necessary, to ensure the proper alignment of each buffer.

Return Values

If elf_update succeeds, it returns the total size of the file image (not the memory image), in bytes. Otherwise an error occurred, and the function returns -1.

Related Information

The elf_begin (elf_begin Subroutine) subroutine, elf_flagdata (elf_flagdata, elf_flagehdr, elf_flagelf, elf_flagphdr, elf_flagscn, elf_flagshdr Subroutine) subroutine, elf32_fsize (elf32_fsize, elf64_fsize Subroutine) subroutine, elf_getdata (elf_getdata, elf_newdata, elf_rawdata Subroutine) subroutine, elf32_getehdr (elf32_getehdr, elf32_newehdr, elf64_getehdr, elf64_newehdr Subroutine) subroutine, elf32_getshdr (elf32_getshdr, elf64_getshdr Subroutine) subroutine, elf32_xlatetof (elf32_xlatetof, elf32_xlatetom, elf64_xlatetof, elf64_xlatetom Subroutine) subroutine.

Introduction to ELF Subroutines.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]