lib/libelf/elf_strptr.3

   1 .\" Copyright (c) 2006 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 .\" $FreeBSD$
  25 .\"
  26 .Dd December 16, 2006
  27 .Dt ELF_STRPTR 3
  28 .Os
  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