287 lines
8.0 KiB
Groff
287 lines
8.0 KiB
Groff
.\" Copyright (c) 2006-2008 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$
|
|
.\"
|
|
.Dd March 19, 2008
|
|
.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 flag 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 example, 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.
|
|
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
|
|
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
|