36c39678d6
with section header tables residing in between other sections. Introduce additional checks for overlaps between section data and the section header table when the application is performing section layout. Document additional error returns. Reported by: Kai Wang <kaiw27 at gmail dot com> Approved by: re (rwatson)
287 lines
8.0 KiB
Groff
287 lines
8.0 KiB
Groff
.\" Copyright (c) 2006,2007 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd September 08, 2007
|
|
.Os
|
|
.Dt ELF_UPDATE 3
|
|
.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
|
|
.Ar elf
|
|
is a descriptor to an ELF object.
|
|
Argument
|
|
.Ar cmd
|
|
can take on the following values:
|
|
.Bl -tag -width "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 back 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.
|
|
.El
|
|
.Ss File Layout
|
|
If the
|
|
.Dv ELF_F_LAYOUT
|
|
flag has been set on the ELF descriptor, the application assumes full
|
|
responsibility for the layout of the ELF object.
|
|
If this bit is not set, the ELF library will compute the layout of the
|
|
file from its associated section descriptors.
|
|
.Pp
|
|
It is the application's responsibility to manage the the following
|
|
structure members in the ELF file:
|
|
.Bl -tag -width indent
|
|
.It "Executable Header"
|
|
The ELF executable header is described in
|
|
.Xr elf 5 .
|
|
The following members of the ELF executable header are the application's
|
|
responsibility:
|
|
.Pp
|
|
.Bl -tag -width "e_ident[EI_OSABI]" -compact
|
|
.It Va e_entry
|
|
Set to the desired entry address for executables.
|
|
.It Va e_flags
|
|
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]"
|
|
Set to the OS ABI desired.
|
|
For
|
|
.Fx
|
|
executables, this field should be set to
|
|
.Dv ELFOSABI_FREEBSD .
|
|
.It Va e_machine
|
|
Set to the desired machine architecture, one of the
|
|
.Dv EM_*
|
|
values in
|
|
.In sys/elf_common.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
|
|
Set to the index of the string table containing
|
|
section names.
|
|
.It Va e_type
|
|
Set to the type of the ELF object, one of the
|
|
.Dv ET_*
|
|
values in
|
|
.In sys/elf_common.h .
|
|
.It Va e_version
|
|
Set to the desired version of the ELF object.
|
|
.El
|
|
.It "Program Header"
|
|
All fields of the entries in the program header table are
|
|
under application control.
|
|
.It "Section Header"
|
|
The ELF section header is described in
|
|
.Xr elf 5 .
|
|
The following members of the ELF section header are the
|
|
application's responsibility:
|
|
.Pp
|
|
.Bl -tag -width "sh_addralign" -compact
|
|
.It Va sh_addr
|
|
Set to the physical 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.
|
|
.It Va sh_entsize
|
|
Set to the size of each entry, for sections containing fixed size
|
|
elements, or set to zero for sections without fixed size elements.
|
|
For section contents of types known to the library, the application
|
|
may leave this field as zero.
|
|
.It Va sh_flags
|
|
Set to the desired section flags.
|
|
.It Va sh_info
|
|
Set as described in
|
|
.Xr elf 5 .
|
|
.It Va sh_link
|
|
Set as described in
|
|
.Xr elf 5 .
|
|
.It Va sh_name
|
|
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
|
|
Set to the type of the section.
|
|
.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 .
|
|
.Pp
|
|
If the application has requested full control over the file's layout by
|
|
setting the
|
|
.Dv ELF_F_LAYOUT
|
|
flag on the ELF descriptor, it should ensure that there are no
|
|
gaps in the coverage of the file's contents.
|
|
.Pp
|
|
All pointers to
|
|
.Vt Elf_Scn
|
|
and
|
|
.Vt Elf_Data
|
|
descriptors associated with descriptor
|
|
.Ar elf
|
|
should be considered as invalid after a call to
|
|
.Fn elf_update .
|
|
.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
|
|
.Ar elf
|
|
was null.
|
|
.It Bq Er ELF_E_ARGUMENT
|
|
Argument
|
|
.Ar cmd
|
|
was not recognized.
|
|
.It Bq Er ELF_E_ARGUMENT
|
|
The argument
|
|
.Ar 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
|
|
.Ar elf
|
|
did not match the class of the file.
|
|
.It Bq Er ELF_E_DATA
|
|
An
|
|
.Vt Elf_Data
|
|
descriptor contained in argument
|
|
.Ar elf
|
|
specified a type incompatible with its containing section.
|
|
.It Bq Er ELF_E_HEADER
|
|
The ELF header in argument
|
|
.Ar 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
|
|
.Ar elf
|
|
specified an alignment incompatible with its containing section.
|
|
.It Bq Er ELF_E_LAYOUT
|
|
Argument
|
|
.Ar elf
|
|
contained section descriptors that overlapped in extent.
|
|
.It Bq Er ELF_E_LAYOUT
|
|
Argument
|
|
.Ar 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 section header table overlapped
|
|
an extent in the object mapped by a section descriptor.
|
|
.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
|
|
.Ar 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
|
|
.Ar elf
|
|
from its underlying file.
|
|
.It Bq Er ELF_E_VERSION
|
|
Argument
|
|
.Ar 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_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
|