lib/libelf/elf_getarsym.3

   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 August 15, 2006
  27 .Os
  28 .Dt ELF_GETARSYM 3
  29 .Sh NAME
  30 .Nm elf_getarsym
  31 .Nd retrieve the symbol table of an archive
  32 .Sh LIBRARY
  33 .Lb libelf
  34 .Sh SYNOPSIS
  35 .In libelf.h
  36 .Ft "Elf_Arsym *"
  37 .Fn elf_getarsym "Elf *elf" "size_t *ptr"
  38 .Sh DESCRIPTION
  39 The function
  40 .Fn elf_getarsym
  41 retrieves the symbol table for an
  42 .Xr ar 1
  43 archive, if one is available.
  44 .Pp
  45 Argument
  46 .Ar elf
  47 should be a descriptor for an
  48 .Xr ar 1
  49 archive opened using
  50 .Fn elf_begin
  51 or
  52 .Fn elf_memory .
  53 .Pp
  54 If the archive
  55 .Ar elf
  56 contains a symbol table with n entries, this function returns a
  57 pointer to an array of n+1
  58 .Vt Elf_Arsym
  59 structures.
  60 An
  61 .Vt Elf_Arsym
  62 structure has the following elements:
  63 .Bl -tag -width indent -compact
  64 .It Vt "char *" Va as_name
  65 This structure member is a pointer to a null-terminated symbol name.
  66 .It Vt "off_t" Va as_off
  67 This structure member contains the byte offset from the beginning of the archive to
  68 the header for the archive member.
  69 This value is suitable for use with
  70 .Xr elf_rand 3 .
  71 .It Vt "unsigned long" Va as_hash
  72 This structure member contains a portable hash value for the symbol
  73 name, as computed by
  74 .Xr elf_hash 3 .
  75 .El
  76 .Pp
  77 The last entry of the returned array will have a NULL value for member
  78 .Va as_name ,
  79 a zero value for member
  80 .Va as_off
  81 and an illegal value of ~0UL for
  82 .Va as_hash .
  83 .Pp
  84 If argument
  85 .Ar ptr
  86 is non-null, the
  87 .Fn elf_getarsym
  88 function will store the number of table entries returned (including the
  89 sentinel entry at the end) into the location it points to.
  90 .Sh RETURN VALUES
  91 Function
  92 .Fn elf_getarsym
  93 returns a pointer to an array of
  94 .Vt Elf_Arsym
  95 structures if successful, or a NULL
  96 pointer if an error was encountered.
  97 .Pp
  98 If argument
  99 .Ar ptr
 100 is non-null and there was no error, the library will store the
 101 number of archive symbol entries returned into the location it
 102 points to.
 103 If argument
 104 .Ar ptr
 105 is non-null and an error was encountered, the library will
 106 set the location pointed to by it to zero.
 107 .Sh ERRORS
 108 Function
 109 .Fn elf_getarsym
 110 may fail with the following errors:
 111 .Bl -tag -width "[ELF_E_RESOURCE]"
 112 .It Bq Er ELF_E_ARGUMENT
 113 Argument
 114 .Ar elf
 115 was NULL.
 116 .It Bq Er ELF_E_ARGUMENT
 117 Argument
 118 .Ar elf
 119 was not a descriptor for an
 120 .Xr ar 1
 121 archive.
 122 .El
 123 .Sh SEE ALSO
 124 .Xr elf 3 ,
 125 .Xr elf_begin 3 ,
 126 .Xr elf_getarhdr 3 ,
 127 .Xr elf_hash 3 ,
 128 .Xr elf_memory 3 ,
 129 .Xr elf_next 3 ,
 130 .Xr elf_rand 3