MFP4: Add an implementation of the ELF(3) and GELF(3) API set.

Bump __FreeBSD_version.

Reviewed by:	jb

1 files changed, 277 insertions, 0 deletions

diff --git a/lib/libelf/elf_update.3 b/lib/libelf/elf_update.3
new file mode 100644
index 0000000..c5c0b5e
--- /dev/null
+++ b/lib/libelf/elf_update.3
@@ -0,0 +1,277 @@
+.\" Copyright (c) 2006 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 August 29, 2006
+.Os
+.Dt ELF 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_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_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 elf_cntl 3 ,
+.Xr elf_fill 3 ,
+.Xr elf_flagehdr 3 ,
+.Xr elf_flagelf 3 ,
+.Xr elf_getscn 3 ,
+.Xr elf_getdata 3 ,
+.Xr elf_newscn 3 ,
+.Xr elf_newdata 3 ,
+.Xr elf_rawdata 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 gelf 3 ,
+.Xr gelf_newehdr 3 ,
+.Xr gelf_newphdr 3 ,
+.Xr elf 5