Return to gelf_getsymshndx.3 CVS log

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

Annotation of src/external/bsd/elftoolchain/dist/libelf/gelf_getsymshndx.3, Revision 1.4

1.2       christos    1: .\"    $NetBSD$
                      2: .\"
1.4     ! jkoshy      3: .\" Copyright (c) 2006,2008,2020 Joseph Koshy.  All rights reserved.
1.1       christos    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: .\"
1.4     ! jkoshy     26: .\" Id: gelf_getsymshndx.3 3928 2021-03-07 19:47:55Z jkoshy
1.1       christos   27: .\"
1.4     ! jkoshy     28: .Dd September 26, 2020
        !            29: .Dt GELF_GETSYMSHNDX 3
1.1       christos   30: .Os
                     31: .Sh NAME
                     32: .Nm gelf_getsymshndx ,
                     33: .Nm gelf_update_symshndx
                     34: .Nd read and update symbol information using extended section indices
                     35: .Sh LIBRARY
                     36: .Lb libelf
                     37: .Sh SYNOPSIS
                     38: .In gelf.h
                     39: .Ft "GElf_Sym *"
                     40: .Fo gelf_getsymshndx
                     41: .Fa "Elf_Data *symdata"
                     42: .Fa "Elf_Data *xndxdata"
                     43: .Fa "int ndx"
                     44: .Fa "GElf_Sym *sym"
                     45: .Fa "Elf32_Word *xndxptr"
                     46: .Fc
                     47: .Ft int
                     48: .Fo gelf_update_symshndx
                     49: .Fa "Elf_Data *symdata"
                     50: .Fa "Elf_Data *xndxdata"
                     51: .Fa "int ndx"
                     52: .Fa "GElf_Sym *sym"
                     53: .Fa "Elf32_Word xndx"
                     54: .Fc
                     55: .Sh DESCRIPTION
                     56: These functions are analogous to
                     57: .Fn gelf_getsym
                     58: and
                     59: .Fn gelf_update_sym
                     60: respectively, but are capable of handling symbol tables using extended
                     61: section numbering.
                     62: .Pp
                     63: Argument
                     64: .Ar symdata
                     65: is an
                     66: .Vt Elf_Data
                     67: descriptor associated with a section of type
                     68: .Dv SHT_SYMTAB .
                     69: Argument
                     70: .Ar xndxdata
                     71: is an
                     72: .Vt Elf_Data
                     73: descriptor associated with a section of type
                     74: .Dv SHT_SYMTAB_SHNDX .
                     75: Argument
                     76: .Ar ndx
                     77: is the index of the symbol table entry being retrieved or updated.
                     78: Argument
                     79: .Ar sym
                     80: is a pointer to a class-independent
                     81: .Vt GElf_Sym
                     82: structure.
                     83: .Vt GElf_Sym
                     84: structures are described in detail in
                     85: .Xr gelf 3 .
                     86: .Pp
                     87: Function
                     88: .Fn gelf_getsymshndx
                     89: retrieves symbol information at index
                     90: .Ar ndx
                     91: from the data descriptor specified by argument
                     92: .Ar symdata
1.4     ! jkoshy     93: and stores it in class-independent form in argument
1.1       christos   94: .Ar sym .
1.4     ! jkoshy     95: Additionally:
        !            96: .Bl -bullet
        !            97: .It
        !            98: If the arguments
        !            99: .Ad xndxdata
        !           100: and
        !           101: .Ar xndxptr
        !           102: are both not
        !           103: .Dv NULL ,
        !           104: it retrieves the extended section index for the
        !           105: symbol from the data buffer pointed to by the
        !           106: argument
1.1       christos  107: .Ar xndxdata
                    108: and stores it into the location pointed to by argument
                    109: .Ar xndxptr .
1.4     ! jkoshy    110: .It
        !           111: Otherwise, if the argument
        !           112: .Ar xndxptr
        !           113: is not
        !           114: .Dv NULL ,
        !           115: a value of zero is stored into the location pointed to by
        !           116: argument
        !           117: .Ar xndxptr .
        !           118: .El
1.1       christos  119: .Pp
                    120: Function
                    121: .Fn gelf_update_symshndx
1.4     ! jkoshy    122: updates the underlying symbol table entry in the data
1.1       christos  123: descriptor
                    124: .Ar symdata
                    125: with the information in argument
                    126: .Ar sym .
                    127: In addition it sets the extended section index in
                    128: data buffer
                    129: .Ar xndxdata
                    130: to the value of argument
                    131: .Ar xndx .
                    132: .Sh RETURN VALUES
                    133: Function
                    134: .Fn gelf_getsymshndx
                    135: returns the value of argument
                    136: .Ar sym
1.4     ! jkoshy    137: if successful, or
        !           138: .Dv NULL
        !           139: in case of an error.
1.1       christos  140: .Pp
                    141: Function
                    142: .Fn gelf_update_symshndx
                    143: returns a non-zero value if successful, or zero in case of an error.
                    144: .Sh ERRORS
                    145: These functions may fail with the following errors:
                    146: .Bl -tag -width "[ELF_E_RESOURCE]"
                    147: .It Bq Er ELF_E_ARGUMENT
                    148: Arguments
                    149: .Ar symdata ,
                    150: .Ar xndxdata ,
                    151: .Ar xndxptr
                    152: or
                    153: .Ar sym
1.4     ! jkoshy    154: were
        !           155: .Dv NULL .
1.1       christos  156: .It Bq Er ELF_E_ARGUMENT
                    157: Argument
                    158: .Ar ndx
                    159: was less than zero, or too large for either of descriptors
                    160: .Ar symdata
                    161: or
                    162: .Ar xndxdata .
                    163: .It Bq Er ELF_E_ARGUMENT
                    164: Data descriptor
                    165: .Ar symdata
                    166: was not associated with a section of type
                    167: .Dv SHT_SYMTAB .
                    168: .It Bq Er ELF_E_ARGUMENT
                    169: Data descriptor
                    170: .Ar xndxdata
                    171: was not associated with a section of type
                    172: .Dv SHT_SYMTAB_SHNDX .
                    173: .It Bq Er ELF_E_ARGUMENT
                    174: Data descriptor
                    175: .Ar symdata
                    176: and
                    177: .Ar xndxdata
                    178: were associated with different ELF objects.
1.4     ! jkoshy    179: .It Bq Er ELF_E_VERSION
        !           180: The
        !           181: .Vt Elf_Data
        !           182: descriptors denoted by arguments
        !           183: .Ar symdata
        !           184: and
        !           185: .Ar xndxdata
        !           186: are associated with an ELF object with an unsupported version.
1.1       christos  187: .El
                    188: .Sh SEE ALSO
                    189: .Xr elf 3 ,
                    190: .Xr elf_getdata 3 ,
                    191: .Xr elf_getscn 3 ,
                    192: .Xr gelf 3 ,
                    193: .Xr gelf_getsym 3 ,
                    194: .Xr gelf_update_sym 3