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