1.\" Copyright (c) 2006,2007-2008 Joseph Koshy. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" This software is provided by Joseph Koshy ``as is'' and 13.\" any express or implied warranties, including, but not limited to, the 14.\" implied warranties of merchantability and fitness for a particular purpose 15.\" are disclaimed. in no event shall Joseph Koshy be liable 16.\" for any direct, indirect, incidental, special, exemplary, or consequential 17.\" damages (including, but not limited to, procurement of substitute goods 18.\" or services; loss of use, data, or profits; or business interruption) 19.\" however caused and on any theory of liability, whether in contract, strict 20.\" liability, or tort (including negligence or otherwise) arising in any way 21.\" out of the use of this software, even if advised of the possibility of 22.\" such damage. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd March 19, 2008 27.Dt ELF_UPDATE 3 28.Os 29.Sh NAME 30.Nm elf_update 31.Nd update an ELF descriptor 32.Sh LIBRARY 33.Lb libelf 34.Sh SYNOPSIS 35.In libelf.h 36.Ft off_t 37.Fn elf_update "Elf *elf" "Elf_Cmd cmd" 38.Sh DESCRIPTION 39Function 40.Fn elf_update 41causes the library to recalculate the structure of an ELF 42object and optionally write out the image of the object 43to file. 44.Pp 45Argument 46.Ar elf 47is a descriptor to an ELF object. 48Argument 49.Ar cmd 50can take on the following values: 51.Bl -tag -width "ELF_C_WRITE" 52.It Dv ELF_C_NULL 53The library will recalculate structural information flagging 54modified structures with the 55.Dv ELF_F_DIRTY 56flag, but will not write back data to the underlying file image. 57.It Dv ELF_C_WRITE 58The library will recalculate structural information and will 59also write the new image to the underlying file. 60.El 61.Ss File Layout 62If the 63.Dv ELF_F_LAYOUT 64flag has been set on the ELF descriptor, the application assumes full 65responsibility for the layout of the ELF object. 66If this flag is not set, the ELF library will compute the layout of the 67file from its associated section descriptors. 68.Pp 69It is the application's responsibility to manage the following 70structure members in the ELF file: 71.Bl -tag -width indent 72.It "Executable Header" 73The ELF executable header is described in 74.Xr elf 5 . 75The following members of the ELF executable header are the application's 76responsibility: 77.Pp 78.Bl -tag -width "e_ident[EI_OSABI]" -compact 79.It Va e_entry 80Set to the desired entry address for executables. 81.It Va e_flags 82Set to the desired processor specific flags. 83.It Va "e_ident[EI_DATA]" 84Must be set to one of 85.Dv ELFDATA2LSB 86or 87.Dv ELFDATA2MSB . 88.It Va "e_ident[EI_OSABI]" 89Set to the OS ABI desired. 90For 91.Fx 92executables, this field should be set to 93.Dv ELFOSABI_FREEBSD . 94.It Va e_machine 95Set to the desired machine architecture, one of the 96.Dv EM_* 97values in 98.In sys/elf_common.h . 99.It Va e_phoff 100If the application is managing the object's layout, it must 101set this field to the file offset of the ELF program header table. 102.It Va e_shoff 103If the application is managing the object's layout, it must 104set this field to the file offset of the ELF section header table. 105.It Va e_shstrndx 106Set to the index of the string table containing 107section names. 108.It Va e_type 109Set to the type of the ELF object, one of the 110.Dv ET_* 111values in 112.In sys/elf_common.h . 113.It Va e_version 114Set to the desired version of the ELF object. 115.El 116.It "Program Header" 117All fields of the entries in the program header table are 118under application control. 119.It "Section Header" 120The ELF section header is described in 121.Xr elf 5 . 122The following members of the ELF section header are the 123application's responsibility: 124.Pp 125.Bl -tag -width "sh_addralign" -compact 126.It Va sh_addr 127Set to the physical memory address where the section should reside. 128.It Va sh_addralign 129If the application is managing the file layout, it must set this 130field to the desired alignment for the section's contents. 131This value must be a power of two. 132.It Va sh_entsize 133Set to the size of each entry, for sections containing fixed size 134elements, or set to zero for sections without fixed size elements. 135If the application is not managing file layout, it may leave this 136field as zero for those sections whose types known to the library. 137.It Va sh_flags 138Set to the desired section flags. 139.It Va sh_info 140Set as described in 141.Xr elf 5 . 142.It Va sh_link 143Set as described in 144.Xr elf 5 . 145.It Va sh_name 146Set to the index of the section's name in the string table containing 147section names. 148.It Va sh_offset 149If the application is managing the file layout, it must set this 150field to the file offset of the section's contents. 151.It Va sh_size 152If the application is managing the file layout, it must set this 153field to the file size of the section's contents. 154.It Va sh_type 155Set to the type of the section. 156.El 157.El 158.Pp 159Gaps in the coverage of the file's contents will be set to the fill value 160specified by 161.Xr elf_fill 3 . 162.Pp 163If the application has requested full control over the file's layout by 164setting the 165.Dv ELF_F_LAYOUT 166flag on the ELF descriptor, it should ensure that there are no 167gaps in the coverage of the file's contents. 168.Pp 169All pointers to 170.Vt Elf_Scn 171and 172.Vt Elf_Data 173descriptors associated with descriptor 174.Ar elf 175should be considered as invalid after a call to 176.Fn elf_update . 177.Sh RETURN VALUES 178Function 179.Fn elf_update 180returns the total size of the file image if successful, or -1 if an 181error occurred. 182.Sh ERRORS 183This function may fail with the following errors: 184.Bl -tag -width "[ELF_E_RESOURCE]" 185.It Bq Er ELF_E_ARGUMENT 186Argument 187.Ar elf 188was null. 189.It Bq Er ELF_E_ARGUMENT 190Argument 191.Ar cmd 192was not recognized. 193.It Bq Er ELF_E_ARGUMENT 194The argument 195.Ar elf 196was not a descriptor for an ELF object. 197.It Bq Er ELF_E_CLASS 198The 199.Va e_ident[EI_CLASS] 200field of the executable header of argument 201.Ar elf 202did not match the class of the file. 203.It Bq Er ELF_E_DATA 204An 205.Vt Elf_Data 206descriptor contained in argument 207.Ar elf 208specified a type incompatible with its containing section. 209.It Bq Er ELF_E_HEADER 210The ELF header in argument 211.Ar elf 212requested a different byte order from the byte order already 213associated with the file. 214.It Bq Er ELF_E_IO 215An I/O error was encountered. 216.It Bq Er ELF_E_LAYOUT 217An 218.Vt Elf_Data 219descriptor contained in argument 220.Ar elf 221specified an alignment incompatible with its containing section. 222.It Bq Er ELF_E_LAYOUT 223Argument 224.Ar elf 225contained section descriptors that overlapped in extent. 226.It Bq Er ELF_E_LAYOUT 227Argument 228.Ar elf 229contained section descriptors that were incorrectly aligned or were 230too small for their data. 231.It Bq Er ELF_E_LAYOUT 232The flag 233.Dv ELF_F_LAYOUT 234was set on the Elf descriptor and the section header table overlapped 235an extent in the object mapped by a section descriptor. 236.It Bq Er ELF_E_MODE 237An 238.Dv ELF_C_WRITE 239operation was requested with an ELF descriptor that was not opened for 240writing or updating. 241.It Bq Er ELF_E_SECTION 242Argument 243.Ar elf 244contained a section with an unrecognized type. 245.It Bq Er ELF_E_SECTION 246The section header at index 247.Dv SHN_UNDEF 248had an illegal section type. 249.It Bq Er ELF_E_SEQUENCE 250An 251.Dv ELF_C_WRITE 252operation was requested after a prior call to 253.Fn elf_cntl elf ELF_C_FDDONE 254disassociated the ELF descriptor 255.Ar elf 256from its underlying file. 257.It Bq Er ELF_E_VERSION 258Argument 259.Ar elf 260had an unsupported version or contained an 261.Vt Elf_Data 262descriptor with an unsupported version. 263.El 264.Sh SEE ALSO 265.Xr elf 3 , 266.Xr elf32_getehdr 3 , 267.Xr elf32_getphdr 3 , 268.Xr elf32_newehdr 3 , 269.Xr elf32_newphdr 3 , 270.Xr elf64_getehdr 3 , 271.Xr elf64_getphdr 3 , 272.Xr elf64_newehdr 3 , 273.Xr elf64_newphdr 3 , 274.Xr elf_cntl 3 , 275.Xr elf_fill 3 , 276.Xr elf_flagehdr 3 , 277.Xr elf_flagelf 3 , 278.Xr elf_getdata 3 , 279.Xr elf_getscn 3 , 280.Xr elf_newdata 3 , 281.Xr elf_newscn 3 , 282.Xr elf_rawdata 3 , 283.Xr gelf 3 , 284.Xr gelf_newehdr 3 , 285.Xr gelf_newphdr 3 , 286.Xr elf 5 287