\"      $NetBSD: elf_update.3,v 1.6 2024/03/03 17:37:33 christos Exp $
\"
\" Copyright (c) 2006-2011 Joseph Koshy.  All rights reserved.
\"
\" Redistribution and use in source and binary forms, with or without
\" modification, are permitted provided that the following conditions
\" are met:
\" 1. Redistributions of source code must retain the above copyright
\"    notice, this list of conditions and the following disclaimer.
\" 2. Redistributions in binary form must reproduce the above copyright
\"    notice, this list of conditions and the following disclaimer in the
\"    documentation and/or other materials provided with the distribution.
\"
\" This software is provided by Joseph Koshy ``as is'' and
\" any express or implied warranties, including, but not limited to, the
\" implied warranties of merchantability and fitness for a particular purpose
\" are disclaimed.  in no event shall Joseph Koshy be liable
\" for any direct, indirect, incidental, special, exemplary, or consequential
\" damages (including, but not limited to, procurement of substitute goods
\" or services; loss of use, data, or profits; or business interruption)
\" however caused and on any theory of liability, whether in contract, strict
\" liability, or tort (including negligence or otherwise) arising in any way
\" out of the use of this software, even if advised of the possibility of
\" such damage.
\"
\" Id: elf_update.3 3957 2022-03-12 14:11:52Z jkoshy
\"
Dd April 22, 2019
Dt ELF_UPDATE 3
Os
Sh NAME
Nm elf_update
Nd update an ELF descriptor
Sh LIBRARY
Lb libelf
Sh SYNOPSIS
In libelf.h
Ft off_t
Fn elf_update "Elf *elf" "Elf_Cmd cmd"
Sh DESCRIPTION
Function
Fn elf_update
causes the library to recalculate the structure of an ELF
object and optionally write out the image of the object
to file.
Pp
Argument
Fa elf
should reference a valid ELF descriptor.
Pp
Argument
Fa cmd
can be one of the following values:
Bl -tag -width "Dv ELF_C_WRITE"
It Dv ELF_C_NULL
The library will recalculate structural information flagging
modified structures with the
Dv ELF_F_DIRTY
flag, but will not write data to the underlying file image.
It Dv ELF_C_WRITE
The library will recalculate structural information and will
also write the new image to the underlying file.
The ELF descriptor referenced by argument
Fa elf
should permit the underlying ELF object to be written or updated
(see
Xr elf_begin 3 ) .
El
Pp
All pointers to
Vt Elf_Scn
and
Vt Elf_Data
descriptors associated with descriptor
Fa elf
should be considered invalid after a call to
Fn elf_update .
Ss Specifying Object Layout
The
Lb libelf
supports two layout modes.
Bl -tag -width indent
It "Library Layout"
If the
Dv ELF_F_LAYOUT
flag is not set on the ELF descriptor, the ELF library will lay out
the ELF object according to the following scheme:
Bl -tag -compact -width "Section Data"
It Em EHDR
The ELF executable header will be placed at the start of the object.
It Em PHDR
If the ELF descriptor contains a program header table, it will be
placed after the Executable Header.
It Em Section Data
ELF section data, if any, will be placed next, keeping each section's
alignment requirements in mind.
It Em SHDR
The ELF section header table, if any, will be placed last.
El
It "Application Controlled Layout"
The application can take full control of the layout of the ELF object
by setting the
Dv ELF_F_LAYOUT
flag on the ELF descriptor (see
Xr elf_flagelf 3 ) .
In this case the library will lay out the ELF object using
application-supplied information as below:
Pp
Bl -tag -compact -width "Section Data"
It Em EHDR
The ELF executable header will be placed at the start of the object.
It Em PHDR
The ELF program header table, if any, it will be placed at the offset
specified in the
Va e_phoff
field of the ELF executable header.
It Em Section Data
The data for each ELF section will be placed at the offset specified
by the
Va sh_offset
field of the section's header.
The size of the section will be taken from the
Va sh_size
field of the section header.
It Em SHDR
The ELF section header table, if any, will be placed at the offset
specified by the
Va e_shoff
field of the executable header.
El
El
Pp
Gaps in the coverage of the file's contents will be set to the fill value
specified by
Xr elf_fill 3 .
Ss Application Supplied Information
The application needs to set the following fields in the data
structures associated with the ELF descriptor prior to calling
Fn elf_update .
Bl -tag -width indent
It "Executable Header"
The fields of the ELF executable header that need to be set by the
application are:
Pp
Bl -tag -width "e_ident[EI_OSABI]" -compact
It Va e_entry
To be set to the desired entry address for executables.
It Va e_flags
To be set to the desired processor specific flags.
It Va "e_ident[EI_DATA]"
Must be set to one of
Dv ELFDATA2LSB
or
Dv ELFDATA2MSB .
It Va "e_ident[EI_OSABI]"
To be set to the OS ABI desired.
For example, for
Fx
executables, this field should be set to
Dv ELFOSABI_FREEBSD .
It Va e_machine
To be set to the desired machine architecture, one of the
Dv EM_*
values in the header file
In elfdefinitions.h .
It Va e_phoff
If the application is managing the object's layout, it must
set this field to the file offset of the ELF program header table.
It Va e_shoff
If the application is managing the object's layout, it must
set this field to the file offset of the ELF section header table.
It Va e_shstrndx
To be set to the index of the string table containing
section names.
It Va e_type
To be set to the type of the ELF object, one of the
Dv ET_*
values in the header file
In elfdefinitions.h .
It Va e_version
To be set to the desired version of the ELF object.
El
It "Program Header"
All fields of the entries in the program header table need to be
set by the application.
It "Section Header"
The fields of ELF section headers that need to be set by the
application are:
Pp
Bl -tag -width "sh_addralign" -compact
It Va sh_addr
To be set to the memory address where the section should reside.
It Va sh_addralign
If the application is managing the file layout, it must set this
field to the desired alignment for the section's contents.
This value must be a power of two and must be at least as large as the
largest alignment needed by any
Vt Elf_Data
descriptor associated with the section.
It Va sh_entsize
To be set to the size of each entry, for sections containing fixed size
elements, or set to zero for sections without fixed size elements.
If the application is not managing file layout, it may leave this
field as zero for those sections whose types are known to the library.
It Va sh_flags
To be set to the desired section flags.
It Va sh_info
To be set as described in
Xr elf 5 .
It Va sh_link
To be set as described in
Xr elf 5 .
It Va sh_name
To be set to the index of the section's name in the string table
containing section names.
It Va sh_offset
If the application is managing the file layout, it must set this
field to the file offset of the section's contents.
It Va sh_size
If the application is managing the file layout, it must set this
field to the file size of the section's contents.
It Va sh_type
To be set to the type of the section.
El
It "Section Data"
The
Vt Elf_Data
descriptors associated with each section specify its contents
(see
Xr elf_getdata 3 ) .
While all the fields in these descriptors are under application
control, the following fields influence object layout:
Bl -tag -width "Va d_align" -compact
It Va d_align
To be set to the desired alignment, within the containing section, of
the descriptor's data.
It Va d_off
If the application is managing object layout, it must set this field
to the file offset, within the section, at which the descriptor's data
should be placed.
It Va d_size
To be set to the size in bytes of the memory representation of the
descriptor's data.
El
El
Sh RETURN VALUES
Function
Fn elf_update
returns the total size of the file image if successful, or -1 if an
error occurred.
Sh ERRORS
This function may fail with the following errors:
Bl -tag -width "[ELF_E_RESOURCE]"
It Bq Er ELF_E_ARGUMENT
Argument
Fa elf
was null.
It Bq Er ELF_E_ARGUMENT
Argument
Fa cmd
was not recognized.
It Bq Er ELF_E_ARGUMENT
The argument
Fa elf
was not a descriptor for an ELF object.
It Bq Er ELF_E_CLASS
The
Va e_ident[EI_CLASS]
field of the executable header of argument
Fa elf
did not match the class of the file.
It Bq Er ELF_E_DATA
An
Vt Elf_Data
descriptor contained in argument
Fa elf
specified an unsupported type.
It Bq Er ELF_E_DATA
An
Vt Elf_Data
descriptor specified an alignment that was zero or was not a power of
two.
It Bq Er ELF_E_HEADER
The ELF header in argument
Fa elf
requested a different byte order from the byte order already
associated with the file.
It Bq Er ELF_E_IO
An I/O error was encountered.
It Bq Er ELF_E_LAYOUT
An
Vt Elf_Data
descriptor contained in argument
Fa elf
specified an alignment incompatible with its containing section.
It Bq Er ELF_E_LAYOUT
Argument
Fa elf
contained section descriptors that overlapped in extent.
It Bq Er ELF_E_LAYOUT
Argument
Fa elf
contained section descriptors that were incorrectly aligned or were
too small for their data.
It Bq Er ELF_E_LAYOUT
The flag
Dv ELF_F_LAYOUT
was set on the Elf descriptor and the executable header overlapped
with the program header table.
It Bq Er ELF_E_LAYOUT
The flag
Dv ELF_F_LAYOUT
was set on the Elf descriptor and the program header table was placed
at a misaligned file offset.
It Bq Er ELF_E_LAYOUT
The flag
Dv ELF_F_LAYOUT
was set on the Elf descriptor and the section header table overlapped
an extent mapped by a section descriptor.
It Bq Er ELF_E_LAYOUT
The
Dv ELF_F_LAYOUT
flag was set on the Elf descriptor, and the
Va d_offset
field in an
Vt Elf_Data
descriptor contained a value that was not a multiple of the
descriptor's specified alignment.
It Bq Er ELF_E_MODE
An
Dv ELF_C_WRITE
operation was requested with an ELF descriptor that was not opened for
writing or updating.
It Bq Er ELF_E_SECTION
Argument
Fa elf
contained a section with an unrecognized type.
It Bq Er ELF_E_SECTION
The section header at index
Dv SHN_UNDEF
had an illegal section type.
It Bq Er ELF_E_SEQUENCE
An
Dv ELF_C_WRITE
operation was requested after a prior call to
Fn elf_cntl elf ELF_C_FDDONE
disassociated the ELF descriptor
Fa elf
from its underlying file.
It Bq Er ELF_E_UNIMPL
Argument
Fa elf
contained a section with an unsupported ELF type.
It Bq Er ELF_E_VERSION
Argument
Fa elf
had an unsupported version or contained an
Vt Elf_Data
descriptor with an unsupported version.
El
Sh SEE ALSO
Xr elf 3 ,
Xr elf32_getehdr 3 ,
Xr elf32_getphdr 3 ,
Xr elf32_newehdr 3 ,
Xr elf32_newphdr 3 ,
Xr elf64_getehdr 3 ,
Xr elf64_getphdr 3 ,
Xr elf64_newehdr 3 ,
Xr elf64_newphdr 3 ,
Xr elf_begin 3 ,
Xr elf_cntl 3 ,
Xr elf_fill 3 ,
Xr elf_flagehdr 3 ,
Xr elf_flagelf 3 ,
Xr elf_getdata 3 ,
Xr elf_getscn 3 ,
Xr elf_newdata 3 ,
Xr elf_newscn 3 ,
Xr elf_rawdata 3 ,
Xr gelf 3 ,
Xr gelf_newehdr 3 ,
Xr gelf_newphdr 3 ,
Xr elf 5

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.