diff options
Diffstat (limited to 'linkers/elftoolchain/libelf/elf_update.3')
| -rw-r--r-- | linkers/elftoolchain/libelf/elf_update.3 | 378 |
1 files changed, 0 insertions, 378 deletions
diff --git a/linkers/elftoolchain/libelf/elf_update.3 b/linkers/elftoolchain/libelf/elf_update.3 deleted file mode 100644 index 40a1e40..0000000 --- a/linkers/elftoolchain/libelf/elf_update.3 +++ /dev/null @@ -1,378 +0,0 @@ -.\" 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 1729 2011-08-14 09:13:00Z jkoshy $ -.\" -.Dd August 14, 2011 -.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 -should reference a valid ELF descriptor. -.Pp -Argument -.Ar 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 -.Ar 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 -.Ar 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 -.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 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 -.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 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 -.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_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 |