.\" $NetBSD: elf_update.3,v 1.1.1.1 2009/12/19 05:43:40 thorpej Exp $ .\" .\" Copyright (c) 2006,2007-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. .\" .\" $FreeBSD: src/lib/libelf/elf_update.3,v 1.6.2.1.2.1 2009/10/25 01:10:29 kensmith Exp $ .\" .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 .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 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