1.\" $NetBSD: elf_getdata.3,v 1.2 2014/03/09 16:58:04 christos Exp $ 2.\" 3.\" Copyright (c) 2006,2008,2010-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_getdata.3 1766 2011-08-22 06:01:03Z jkoshy 27.\" 28.Dd January 26, 2011 29.Os 30.Dt ELF_GETDATA 3 31.Sh NAME 32.Nm elf_getdata , 33.Nm elf_newdata , 34.Nm elf_rawdata 35.Nd iterate through or allocate section data 36.Sh LIBRARY 37.Lb libelf 38.Sh SYNOPSIS 39.In libelf.h 40.Ft "Elf_Data *" 41.Fn elf_getdata "Elf_Scn *scn" "Elf_Data *data" 42.Ft "Elf_Data *" 43.Fn elf_newdata "Elf_Scn *scn" 44.Ft "Elf_Data *" 45.Fn elf_rawdata "Elf_Scn *scn" "Elf_Data *data" 46.Sh DESCRIPTION 47These functions are used to access and manipulate data descriptors 48associated with section descriptors. 49Data descriptors used by the ELF library are described in 50.Xr elf 3 . 51.Pp 52Function 53.Fn elf_getdata 54will return the next data descriptor associated with section descriptor 55.Ar scn . 56The returned data descriptor will be setup to contain translated data. 57Argument 58.Ar data 59may be 60.Dv NULL , 61in which case the function returns the first data descriptor 62associated with section 63.Ar scn . 64If argument 65.Ar data 66is not 67.Dv NULL , 68it must be a pointer to a data descriptor associated with 69section descriptor 70.Ar scn , 71and function 72.Fn elf_getdata 73will return a pointer to the next data descriptor for the section, 74or 75.Dv NULL 76when the end of the section's descriptor list is reached. 77.Pp 78Function 79.Fn elf_newdata 80will allocate a new data descriptor and append it to the list of data 81descriptors associated with section descriptor 82.Ar scn . 83The new data descriptor will be initialized as follows: 84.Bl -tag -width "d_version" -compact -offset indent 85.It Va d_align 86Set to 1. 87.It Va d_buf 88Initialized to. 89.Dv NULL . 90.It Va d_off 91Set to (off_t) -1. 92This field is under application control if the 93.Dv ELF_F_LAYOUT 94flag was set on the ELF descriptor. 95.It Va d_size 96Set to zero. 97.It Va d_type 98Initialized to 99.Dv ELF_T_BYTE . 100.It Va d_version 101Set to the current working version of the library, as set by 102.Xr elf_version 3 . 103.El 104The application must set these values as appropriate before 105calling 106.Xr elf_update 3 . 107Section 108.Ar scn 109must be associated with an ELF file opened for writing. 110If the application has not requested full control of layout by 111setting the 112.Dv ELF_F_LAYOUT 113flag on descriptor 114.Ar elf , 115then the data referenced by the returned descriptor will be positioned 116after the existing content of the section, honoring the file alignment 117specified in member 118.Va d_align . 119On successful completion of a call to 120.Fn elf_newdata , 121the ELF library will mark the section 122.Ar scn 123as 124.Dq dirty . 125.Pp 126Function 127.Fn elf_rawdata 128is used to step through the data descriptors associated with 129section 130.Ar scn . 131In contrast to function 132.Fn elf_getdata , 133this function returns untranslated data. 134If argument 135.Ar data 136is 137.Dv NULL , 138the first data descriptor associated with section 139.Ar scn 140is returned. 141If argument 142.Ar data 143is not 144.Dv NULL , 145is must be a data descriptor associated with 146section 147.Ar scn , 148and function 149.Fn elf_rawdata 150will return the next data descriptor in the list, or 151.Dv NULL 152if no further descriptors are present. 153Function 154.Fn elf_rawdata 155always returns 156.Vt Elf_Data 157structures of type 158.Dv ELF_T_BYTE . 159.Ss Special handling of zero-sized and SHT_NOBITS sections 160For sections of type 161.Dv SHT_NOBITS, 162and for zero-sized sections, 163the functions 164.Fn elf_getdata 165and 166.Fn elf_rawdata 167return a pointer to a valid 168.Vt Elf_Data 169structure that has its 170.Va d_buf 171member set to 172.Dv NULL 173and its 174.Va d_size 175member set to the size of the section. 176.Pp 177If an application wishes to create a section of type 178.Dv SHT_NOBITS , 179it should add a data buffer to the section using function 180.Fn elf_newdata . 181It should then set the 182.Va d_buf 183and 184.Va d_size 185members of the returned 186.Vt Elf_Data 187structure to 188.Dv NULL 189and the desired size of the section respectively. 190.Sh RETURN VALUES 191These functions return a valid pointer to a data descriptor if successful, or 192.Dv NULL 193if an error occurs. 194.Sh ERRORS 195These functions may fail with the following errors: 196.Bl -tag -width "[ELF_E_RESOURCE]" 197.It Bq Er ELF_E_ARGUMENT 198Either of the arguments 199.Ar scn 200or 201.Ar data 202was 203.Dv NULL . 204.It Bq Er ELF_E_ARGUMENT 205The data descriptor referenced by argument 206.Ar data 207is not associated with section descriptor 208.Ar scn . 209.It Bq Er ELF_E_ARGUMENT 210The section denoted by argument 211.Ar scn 212had no data associated with it. 213.It Bq Er ELF_E_DATA 214Retrieval of data from the underlying object failed. 215.It Bq Er ELF_E_RESOURCE 216An out of memory condition was detected. 217.It Bq Er ELF_E_SECTION 218Section 219.Ar scn 220had type 221.Dv SHT_NULL . 222.It Bq Er ELF_E_SECTION 223The type of the section 224.Ar scn 225was not recognized by the library. 226.It Bq Er ELF_E_SECTION 227The size of the section 228.Ar scn 229is not a multiple of the file size for its section type. 230.It Bq Er ELF_E_SECTION 231The file offset for section 232.Ar scn 233is incorrect. 234.It Bq Er ELF_E_UNIMPL 235The section type associated with section 236.Ar scn 237is currently unsupported by the library. 238.El 239.Sh SEE ALSO 240.Xr elf 3 , 241.Xr elf_flagdata 3 , 242.Xr elf_flagscn 3 , 243.Xr elf_getscn 3 , 244.Xr elf_getshdr 3 , 245.Xr elf_newscn 3 , 246.Xr elf_rawfile 3 , 247.Xr elf_update 3 , 248.Xr elf_version 3 , 249.Xr gelf 3 250