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

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