Return to elf_getarsym.3 CVS log

Up to [cvs.NetBSD.org] / src / external / bsd / elftoolchain / dist / libelf

Annotation of src/external/bsd/elftoolchain/dist/libelf/elf_getarsym.3, Revision 1.1.1.1

1.1       christos    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: elf_getarsym.3 189 2008-07-20 10:38:08Z jkoshy
                     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