external/bsd/elftoolchain/dist/libelf/elf_strptr.3

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