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