1  .\" Copyright (c) 2006,2008 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$
 25  .\"
 26  .Dd December 16, 2006
 27  .Os
 28  .Dt ELF_STRPTR 3
 29  .Sh NAME
 30  .Nm elf_strptr
 31  .Nd retrieve a string pointer in a string table
 32  .Sh LIBRARY
 33  .Lb libelf
 34  .Sh SYNOPSIS
 35  .In libelf.h
 36  .Ft "char *"
 37  .Fn elf_strptr "Elf *elf" "size_t scndx" "size_t stroffset"
 38  .Sh DESCRIPTION
 39  Function
 40  .Fn elf_strptr
 41  allows an application to convert a string table offset to a string
 42  pointer, correctly translating the offset in the presence
 43  of multiple
 44  .Vt Elf_Data
 45  descriptors covering the contents of the section.
 46  .Pp
 47  Argument
 48  .Ar elf
 49  is a descriptor for an ELF object.
 50  Argument
 51  .Ar scndx
 52  is the section index for an ELF string table.
 53  Argument
 54  .Ar stroffset
 55  is the index of the desired string in the string
 56  table.
 57  .Sh RETURN VALUES
 58  Function
 59  .Fn elf_strptr
 60  returns a valid pointer on success or NULL in case an error was
 61  encountered.
 62  .Sh ERRORS
 63  .Bl -tag -width "[ELF_E_RESOURCE]"
 64  .It Bq Er ELF_E_ARGUMENT
 65  Argument
 66  .Ar elf
 67  was NULL
 68  .It Bq Er ELF_E_ARGUMENT
 69  Argument
 70  .Ar elf
 71  was not a descriptor for an ELF object.
 72  .It Bq Er ELF_E_ARGUMENT
 73  Argument
 74  .Ar scndx
 75  was not the section index for a string table.
 76  .It Bq Er ELF_E_ARGUMENT
 77  Argument
 78  .Ar stroffset
 79  exceeded the size of the string table.
 80  .It Bq Er ELF_E_ARGUMENT
 81  Argument
 82  .Ar stroffset
 83  index an unallocated region of the string table.
 84  .It Bq Er ELF_E_DATA
 85  Offset
 86  .Ar stroffset
 87  indexed a region that was not covered by any Elf_Data
 88  descriptor.
 89  .It Bq Er ELF_E_DATA
 90  An erroneous
 91  .Vt Elf_Data
 92  descriptor was part of the section specified by argument
 93  .Ar scndx .
 94  .It Bq Er ELF_E_HEADER
 95  ELF descriptor
 96  .Ar elf
 97  contained an invalid section header.
 98  .It Bq Er ELF_E_RESOURCE
 99  An out of memory condition was detected.
100  .It Bq Er ELF_E_SECTION
101  Section
102  .Ar scndx
103  contained a malformed section header.
104  .It Bq Er ELF_E_SECTION
105  The ELF descriptor in argument
106  .Ar elf
107  did not adhere to the conventions used for extended numbering.
108  .El
109  .Sh SEE ALSO
110  .Xr elf 3 ,
111  .Xr elf32_getshdr 3 ,
112  .Xr elf64_getshdr 3 ,
113  .Xr elf_getdata 3 ,
114  .Xr elf_rawdata 3 ,
115  .Xr gelf 3 ,
116  .Xr gelf_getshdr 3