1*0a6a1f1dSLionel Sambuc.\" $NetBSD: elf_getscn.3,v 1.2 2014/03/09 16:58:04 christos Exp $ 2*0a6a1f1dSLionel Sambuc.\" 3*0a6a1f1dSLionel Sambuc.\" Copyright (c) 2006-2008 Joseph Koshy. All rights reserved. 4*0a6a1f1dSLionel Sambuc.\" 5*0a6a1f1dSLionel Sambuc.\" Redistribution and use in source and binary forms, with or without 6*0a6a1f1dSLionel Sambuc.\" modification, are permitted provided that the following conditions 7*0a6a1f1dSLionel Sambuc.\" are met: 8*0a6a1f1dSLionel Sambuc.\" 1. Redistributions of source code must retain the above copyright 9*0a6a1f1dSLionel Sambuc.\" notice, this list of conditions and the following disclaimer. 10*0a6a1f1dSLionel Sambuc.\" 2. Redistributions in binary form must reproduce the above copyright 11*0a6a1f1dSLionel Sambuc.\" notice, this list of conditions and the following disclaimer in the 12*0a6a1f1dSLionel Sambuc.\" documentation and/or other materials provided with the distribution. 13*0a6a1f1dSLionel Sambuc.\" 14*0a6a1f1dSLionel Sambuc.\" This software is provided by Joseph Koshy ``as is'' and 15*0a6a1f1dSLionel Sambuc.\" any express or implied warranties, including, but not limited to, the 16*0a6a1f1dSLionel Sambuc.\" implied warranties of merchantability and fitness for a particular purpose 17*0a6a1f1dSLionel Sambuc.\" are disclaimed. in no event shall Joseph Koshy be liable 18*0a6a1f1dSLionel Sambuc.\" for any direct, indirect, incidental, special, exemplary, or consequential 19*0a6a1f1dSLionel Sambuc.\" damages (including, but not limited to, procurement of substitute goods 20*0a6a1f1dSLionel Sambuc.\" or services; loss of use, data, or profits; or business interruption) 21*0a6a1f1dSLionel Sambuc.\" however caused and on any theory of liability, whether in contract, strict 22*0a6a1f1dSLionel Sambuc.\" liability, or tort (including negligence or otherwise) arising in any way 23*0a6a1f1dSLionel Sambuc.\" out of the use of this software, even if advised of the possibility of 24*0a6a1f1dSLionel Sambuc.\" such damage. 25*0a6a1f1dSLionel Sambuc.\" 26*0a6a1f1dSLionel Sambuc.\" Id: elf_getscn.3 189 2008-07-20 10:38:08Z jkoshy 27*0a6a1f1dSLionel Sambuc.\" 28*0a6a1f1dSLionel Sambuc.Dd October 22, 2007 29*0a6a1f1dSLionel Sambuc.Os 30*0a6a1f1dSLionel Sambuc.Dt ELF_GETSCN 3 31*0a6a1f1dSLionel Sambuc.Sh NAME 32*0a6a1f1dSLionel Sambuc.Nm elf_getscn , 33*0a6a1f1dSLionel Sambuc.Nm elf_ndxscn , 34*0a6a1f1dSLionel Sambuc.Nm elf_newscn , 35*0a6a1f1dSLionel Sambuc.Nm elf_nextscn 36*0a6a1f1dSLionel Sambuc.Nd get/allocate section information for an ELF object 37*0a6a1f1dSLionel Sambuc.Sh LIBRARY 38*0a6a1f1dSLionel Sambuc.Lb libelf 39*0a6a1f1dSLionel Sambuc.Sh SYNOPSIS 40*0a6a1f1dSLionel Sambuc.In libelf.h 41*0a6a1f1dSLionel Sambuc.Ft "Elf_Scn *" 42*0a6a1f1dSLionel Sambuc.Fn elf_getscn "Elf *elf" "size_t index" 43*0a6a1f1dSLionel Sambuc.Ft size_t 44*0a6a1f1dSLionel Sambuc.Fn elf_ndxscn "Elf_Scn *scn" 45*0a6a1f1dSLionel Sambuc.Ft "Elf_Scn *" 46*0a6a1f1dSLionel Sambuc.Fn elf_newscn "Elf *elf" 47*0a6a1f1dSLionel Sambuc.Ft "Elf_Scn *" 48*0a6a1f1dSLionel Sambuc.Fn elf_nextscn "Elf *elf" "Elf_Scn *scn" 49*0a6a1f1dSLionel Sambuc.Sh DESCRIPTION 50*0a6a1f1dSLionel SambucThese functions are used to iterate through the sections associated 51*0a6a1f1dSLionel Sambucwith an ELF descriptor. 52*0a6a1f1dSLionel Sambuc.Pp 53*0a6a1f1dSLionel SambucFunction 54*0a6a1f1dSLionel Sambuc.Fn elf_getscn 55*0a6a1f1dSLionel Sambucwill return a section descriptor for the section at index 56*0a6a1f1dSLionel Sambuc.Ar index 57*0a6a1f1dSLionel Sambucin the object denoted by ELF descriptor 58*0a6a1f1dSLionel Sambuc.Ar elf . 59*0a6a1f1dSLionel SambucAn error will be signalled if the specified section does not 60*0a6a1f1dSLionel Sambucexist. 61*0a6a1f1dSLionel Sambuc.Pp 62*0a6a1f1dSLionel SambucFunction 63*0a6a1f1dSLionel Sambuc.Fn elf_ndxscn 64*0a6a1f1dSLionel Sambucreturns the section table index associated with section descriptor 65*0a6a1f1dSLionel Sambuc.Ar scn . 66*0a6a1f1dSLionel Sambuc.Pp 67*0a6a1f1dSLionel SambucFunction 68*0a6a1f1dSLionel Sambuc.Fn elf_newscn 69*0a6a1f1dSLionel Sambuccreates a new section and appends it to the list of sections 70*0a6a1f1dSLionel Sambucassociated with descriptor 71*0a6a1f1dSLionel Sambuc.Ar elf . 72*0a6a1f1dSLionel SambucThe library will automatically increment the 73*0a6a1f1dSLionel Sambuc.Va e_shnum 74*0a6a1f1dSLionel Sambucfield of the ELF header associated with descriptor 75*0a6a1f1dSLionel Sambuc.Ar elf , 76*0a6a1f1dSLionel Sambucand will set the 77*0a6a1f1dSLionel Sambuc.Dv ELF_F_DIRTY 78*0a6a1f1dSLionel Sambucflag on the returned section descriptor. 79*0a6a1f1dSLionel SambucFor ELF descriptors opened for writing, the ELF library will 80*0a6a1f1dSLionel Sambucautomatically create an empty section at index zero 81*0a6a1f1dSLionel Sambuc.Dv ( SHN_UNDEF ) 82*0a6a1f1dSLionel Sambucon the first call to 83*0a6a1f1dSLionel Sambuc.Fn elf_newscn . 84*0a6a1f1dSLionel Sambuc.Pp 85*0a6a1f1dSLionel SambucFunction 86*0a6a1f1dSLionel Sambuc.Fn elf_nextscn 87*0a6a1f1dSLionel Sambuctakes a section descriptor 88*0a6a1f1dSLionel Sambuc.Ar scn 89*0a6a1f1dSLionel Sambucand returns a pointer to the section descriptor at the next higher 90*0a6a1f1dSLionel Sambucindex. 91*0a6a1f1dSLionel SambucArgument 92*0a6a1f1dSLionel Sambuc.Ar scn 93*0a6a1f1dSLionel Sambucis allowed to be NULL, in which case this function will return a 94*0a6a1f1dSLionel Sambucpointer to the section descriptor at index 1. 95*0a6a1f1dSLionel SambucIf no further sections are present, function 96*0a6a1f1dSLionel Sambuc.Fn elf_nextscn 97*0a6a1f1dSLionel Sambucwill return a NULL pointer. 98*0a6a1f1dSLionel Sambuc.Sh RETURN VALUES 99*0a6a1f1dSLionel SambucFunctions 100*0a6a1f1dSLionel Sambuc.Fn elf_getscn , 101*0a6a1f1dSLionel Sambuc.Fn elf_newscn 102*0a6a1f1dSLionel Sambucand 103*0a6a1f1dSLionel Sambuc.Fn elf_nextscn 104*0a6a1f1dSLionel Sambucreturn a valid pointer to a section descriptor if successful, or 105*0a6a1f1dSLionel SambucNULL if an error occurs. 106*0a6a1f1dSLionel Sambuc.Pp 107*0a6a1f1dSLionel SambucFunction 108*0a6a1f1dSLionel Sambuc.Fn elf_ndxscn 109*0a6a1f1dSLionel Sambucreturns a valid section table index if successful, or 110*0a6a1f1dSLionel Sambuc.Dv SHN_UNDEF 111*0a6a1f1dSLionel Sambucif an error occurs. 112*0a6a1f1dSLionel Sambuc.Sh ERRORS 113*0a6a1f1dSLionel SambucThese functions may fail with the following errors: 114*0a6a1f1dSLionel Sambuc.Bl -tag -width "[ELF_E_RESOURCE]" 115*0a6a1f1dSLionel Sambuc.It Bq Er ELF_E_ARGUMENT 116*0a6a1f1dSLionel SambucArguments 117*0a6a1f1dSLionel Sambuc.Ar elf 118*0a6a1f1dSLionel Sambucor 119*0a6a1f1dSLionel Sambuc.Ar scn 120*0a6a1f1dSLionel Sambucwere NULL. 121*0a6a1f1dSLionel Sambuc.It Bq Er ELF_E_ARGUMENT 122*0a6a1f1dSLionel SambucArgument 123*0a6a1f1dSLionel Sambuc.Ar index 124*0a6a1f1dSLionel Sambucexceeded the current number of sections in the ELF object. 125*0a6a1f1dSLionel Sambuc.It Bq Er ELF_E_ARGUMENT 126*0a6a1f1dSLionel SambucArgument 127*0a6a1f1dSLionel Sambuc.Ar elf 128*0a6a1f1dSLionel Sambucwas not a descriptor for an ELF file. 129*0a6a1f1dSLionel Sambuc.It Bq Er ELF_E_ARGUMENT 130*0a6a1f1dSLionel SambucSection descriptor 131*0a6a1f1dSLionel Sambuc.Ar scn 132*0a6a1f1dSLionel Sambucwas not associated with ELF descriptor 133*0a6a1f1dSLionel Sambuc.Ar elf . 134*0a6a1f1dSLionel Sambuc.It Bq Er ELF_E_CLASS 135*0a6a1f1dSLionel SambucDescriptor 136*0a6a1f1dSLionel Sambuc.Ar elf 137*0a6a1f1dSLionel Sambucwas of an unknown ELF class. 138*0a6a1f1dSLionel Sambuc.It Bq Er ELF_E_SECTION 139*0a6a1f1dSLionel SambucArgument 140*0a6a1f1dSLionel Sambuc.Ar elf 141*0a6a1f1dSLionel Sambucspecified extended section numbering in the ELF header with the section header at 142*0a6a1f1dSLionel Sambucindex 143*0a6a1f1dSLionel Sambuc.Dv SHN_UNDEF 144*0a6a1f1dSLionel Sambucnot being of type 145*0a6a1f1dSLionel Sambuc.Dv SHT_NULL . 146*0a6a1f1dSLionel Sambuc.El 147*0a6a1f1dSLionel Sambuc.Sh SEE ALSO 148*0a6a1f1dSLionel Sambuc.Xr elf 3 , 149*0a6a1f1dSLionel Sambuc.Xr elf_flagdata 3 , 150*0a6a1f1dSLionel Sambuc.Xr elf_flagscn 3 , 151*0a6a1f1dSLionel Sambuc.Xr elf_getdata 3 , 152*0a6a1f1dSLionel Sambuc.Xr elf_getshdr 3 , 153*0a6a1f1dSLionel Sambuc.Xr gelf 3 154