1.\" Copyright (c) 2006-2011 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.\" $Id: elf_update.3 3734 2019-04-22 14:10:49Z jkoshy $ 25.\" 26.Dd April 22, 2019 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 47should reference a valid ELF descriptor. 48.Pp 49Argument 50.Ar cmd 51can be one of the following values: 52.Bl -tag -width "Dv ELF_C_WRITE" 53.It Dv ELF_C_NULL 54The library will recalculate structural information flagging 55modified structures with the 56.Dv ELF_F_DIRTY 57flag, but will not write data to the underlying file image. 58.It Dv ELF_C_WRITE 59The library will recalculate structural information and will 60also write the new image to the underlying file. 61The ELF descriptor referenced by argument 62.Ar elf 63should permit the underlying ELF object to be written or updated 64(see 65.Xr elf_begin 3 ) . 66.El 67.Pp 68All pointers to 69.Vt Elf_Scn 70and 71.Vt Elf_Data 72descriptors associated with descriptor 73.Ar elf 74should be considered invalid after a call to 75.Fn elf_update . 76.Ss Specifying Object Layout 77The 78.Lb libelf 79supports two layout modes. 80.Bl -tag -width indent 81.It "Library Layout" 82If the 83.Dv ELF_F_LAYOUT 84flag is not set on the ELF descriptor, the ELF library will lay out 85the ELF object according to the following scheme: 86.Bl -tag -compact -width "Section Data" 87.It Em EHDR 88The ELF executable header will be placed at the start of the object. 89.It Em PHDR 90If the ELF descriptor contains a program header table, it will be 91placed after the Executable Header. 92.It Em Section Data 93ELF section data, if any, will be placed next, keeping each section's 94alignment requirements in mind. 95.It Em SHDR 96The ELF section header table, if any, will be placed last. 97.El 98.It "Application Controlled Layout" 99The application can take full control of the layout of the ELF object 100by setting the 101.Dv ELF_F_LAYOUT 102flag on the ELF descriptor (see 103.Xr elf_flagelf 3 ) . 104In this case the library will lay out the ELF object using 105application-supplied information as below: 106.Pp 107.Bl -tag -compact -width "Section Data" 108.It Em EHDR 109The ELF executable header will be placed at the start of the object. 110.It Em PHDR 111The ELF program header table, if any, it will be placed at the offset 112specified in the 113.Va e_phoff 114field of the ELF executable header. 115.It Em Section Data 116The data for each ELF section will be placed at the offset specified 117by the 118.Va sh_offset 119field of the section's header. 120The size of the section will be taken from the 121.Va sh_size 122field of the section header. 123.It Em SHDR 124The ELF section header table, if any, will be placed at the offset 125specified by the 126.Va e_shoff 127field of the executable header. 128.El 129.El 130.Pp 131Gaps in the coverage of the file's contents will be set to the fill value 132specified by 133.Xr elf_fill 3 . 134.Ss Application Supplied Information 135The application needs to set the following fields in the data 136structures associated with the ELF descriptor prior to calling 137.Fn elf_update . 138.Bl -tag -width indent 139.It "Executable Header" 140The fields of the ELF executable header that need to be set by the 141application are: 142.Pp 143.Bl -tag -width "e_ident[EI_OSABI]" -compact 144.It Va e_entry 145To be set to the desired entry address for executables. 146.It Va e_flags 147To be set to the desired processor specific flags. 148.It Va "e_ident[EI_DATA]" 149Must be set to one of 150.Dv ELFDATA2LSB 151or 152.Dv ELFDATA2MSB . 153.It Va "e_ident[EI_OSABI]" 154To be set to the OS ABI desired. 155For example, for 156.Fx 157executables, this field should be set to 158.Dv ELFOSABI_FREEBSD . 159.It Va e_machine 160To be set to the desired machine architecture, one of the 161.Dv EM_* 162values in the header file 163.In elfdefinitions.h . 164.It Va e_phoff 165If the application is managing the object's layout, it must 166set this field to the file offset of the ELF program header table. 167.It Va e_shoff 168If the application is managing the object's layout, it must 169set this field to the file offset of the ELF section header table. 170.It Va e_shstrndx 171To be set to the index of the string table containing 172section names. 173.It Va e_type 174To be set to the type of the ELF object, one of the 175.Dv ET_* 176values in the header file 177.In elfdefinitions.h . 178.It Va e_version 179To be set to the desired version of the ELF object. 180.El 181.It "Program Header" 182All fields of the entries in the program header table need to be 183set by the application. 184.It "Section Header" 185The fields of ELF section headers that need to be set by the 186application are: 187.Pp 188.Bl -tag -width "sh_addralign" -compact 189.It Va sh_addr 190To be set to the memory address where the section should reside. 191.It Va sh_addralign 192If the application is managing the file layout, it must set this 193field to the desired alignment for the section's contents. 194This value must be a power of two and must be at least as large as the 195largest alignment needed by any 196.Vt Elf_Data 197descriptor associated with the section. 198.It Va sh_entsize 199To be set to the size of each entry, for sections containing fixed size 200elements, or set to zero for sections without fixed size elements. 201If the application is not managing file layout, it may leave this 202field as zero for those sections whose types are known to the library. 203.It Va sh_flags 204To be set to the desired section flags. 205.It Va sh_info 206To be set as described in 207.Xr elf 5 . 208.It Va sh_link 209To be set as described in 210.Xr elf 5 . 211.It Va sh_name 212To be set to the index of the section's name in the string table 213containing section names. 214.It Va sh_offset 215If the application is managing the file layout, it must set this 216field to the file offset of the section's contents. 217.It Va sh_size 218If the application is managing the file layout, it must set this 219field to the file size of the section's contents. 220.It Va sh_type 221To be set to the type of the section. 222.El 223.It "Section Data" 224The 225.Vt Elf_Data 226descriptors associated with each section specify its contents 227(see 228.Xr elf_getdata 3 ) . 229While all the fields in these descriptors are under application 230control, the following fields influence object layout: 231.Bl -tag -width "Va d_align" -compact 232.It Va d_align 233To be set to the desired alignment, within the containing section, of 234the descriptor's data. 235.It Va d_off 236If the application is managing object layout, it must set this field 237to the file offset, within the section, at which the descriptor's data 238should be placed. 239.It Va d_size 240To be set to the size in bytes of the memory representation of the 241descriptor's data. 242.El 243.El 244.Sh RETURN VALUES 245Function 246.Fn elf_update 247returns the total size of the file image if successful, or -1 if an 248error occurred. 249.Sh ERRORS 250This function may fail with the following errors: 251.Bl -tag -width "[ELF_E_RESOURCE]" 252.It Bq Er ELF_E_ARGUMENT 253Argument 254.Ar elf 255was null. 256.It Bq Er ELF_E_ARGUMENT 257Argument 258.Ar cmd 259was not recognized. 260.It Bq Er ELF_E_ARGUMENT 261The argument 262.Ar elf 263was not a descriptor for an ELF object. 264.It Bq Er ELF_E_CLASS 265The 266.Va e_ident[EI_CLASS] 267field of the executable header of argument 268.Ar elf 269did not match the class of the file. 270.It Bq Er ELF_E_DATA 271An 272.Vt Elf_Data 273descriptor contained in argument 274.Ar elf 275specified an unsupported type. 276.It Bq Er ELF_E_DATA 277An 278.Vt Elf_Data 279descriptor specified an alignment that was zero or was not a power of 280two. 281.It Bq Er ELF_E_HEADER 282The ELF header in argument 283.Ar elf 284requested a different byte order from the byte order already 285associated with the file. 286.It Bq Er ELF_E_IO 287An I/O error was encountered. 288.It Bq Er ELF_E_LAYOUT 289An 290.Vt Elf_Data 291descriptor contained in argument 292.Ar elf 293specified an alignment incompatible with its containing section. 294.It Bq Er ELF_E_LAYOUT 295Argument 296.Ar elf 297contained section descriptors that overlapped in extent. 298.It Bq Er ELF_E_LAYOUT 299Argument 300.Ar elf 301contained section descriptors that were incorrectly aligned or were 302too small for their data. 303.It Bq Er ELF_E_LAYOUT 304The flag 305.Dv ELF_F_LAYOUT 306was set on the Elf descriptor and the executable header overlapped 307with the program header table. 308.It Bq Er ELF_E_LAYOUT 309The flag 310.Dv ELF_F_LAYOUT 311was set on the Elf descriptor and the program header table was placed 312at a misaligned file offset. 313.It Bq Er ELF_E_LAYOUT 314The flag 315.Dv ELF_F_LAYOUT 316was set on the Elf descriptor and the section header table overlapped 317an extent mapped by a section descriptor. 318.It Bq Er ELF_E_LAYOUT 319The 320.Dv ELF_F_LAYOUT 321flag was set on the Elf descriptor, and the 322.Va d_offset 323field in an 324.Vt Elf_Data 325descriptor contained a value that was not a multiple of the 326descriptor's specified alignment. 327.It Bq Er ELF_E_MODE 328An 329.Dv ELF_C_WRITE 330operation was requested with an ELF descriptor that was not opened for 331writing or updating. 332.It Bq Er ELF_E_SECTION 333Argument 334.Ar elf 335contained a section with an unrecognized type. 336.It Bq Er ELF_E_SECTION 337The section header at index 338.Dv SHN_UNDEF 339had an illegal section type. 340.It Bq Er ELF_E_SEQUENCE 341An 342.Dv ELF_C_WRITE 343operation was requested after a prior call to 344.Fn elf_cntl elf ELF_C_FDDONE 345disassociated the ELF descriptor 346.Ar elf 347from its underlying file. 348.It Bq Er ELF_E_UNIMPL 349Argument 350.Ar elf 351contained a section with an unsupported ELF type. 352.It Bq Er ELF_E_VERSION 353Argument 354.Ar elf 355had an unsupported version or contained an 356.Vt Elf_Data 357descriptor with an unsupported version. 358.El 359.Sh SEE ALSO 360.Xr elf 3 , 361.Xr elf32_getehdr 3 , 362.Xr elf32_getphdr 3 , 363.Xr elf32_newehdr 3 , 364.Xr elf32_newphdr 3 , 365.Xr elf64_getehdr 3 , 366.Xr elf64_getphdr 3 , 367.Xr elf64_newehdr 3 , 368.Xr elf64_newphdr 3 , 369.Xr elf_begin 3 , 370.Xr elf_cntl 3 , 371.Xr elf_fill 3 , 372.Xr elf_flagehdr 3 , 373.Xr elf_flagelf 3 , 374.Xr elf_getdata 3 , 375.Xr elf_getscn 3 , 376.Xr elf_newdata 3 , 377.Xr elf_newscn 3 , 378.Xr elf_rawdata 3 , 379.Xr gelf 3 , 380.Xr gelf_newehdr 3 , 381.Xr gelf_newphdr 3 , 382.Xr elf 5 383