'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved 
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH gelf 3ELF "8 June 2004" "SunOS 5.11" "ELF Library Functions"
.SH NAME
gelf, gelf_checksum, gelf_fsize, gelf_getcap, gelf_getclass, gelf_getdyn,
gelf_getehdr, gelf_getmove, gelf_getphdr, gelf_getrel, gelf_getrela,
gelf_getshdr, gelf_getsym, gelf_getsyminfo, gelf_getsymshndx, gelf_newehdr,
gelf_newphdr, gelf_update_cap, gelf_update_dyn, gelf_update_ehdr,
gelf_update_getmove, gelf_update_move, gelf_update_phdr, gelf_update_rel,
gelf_update_rela, gelf_update_shdr, gelf_update_sym, gelf_update_symshndx,
gelf_update_syminfo, gelf_xlatetof, gelf_xlatetom \- generic class-independent
ELF interface
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR...  \fB\(milelf\fR [ \fIlibrary\fR... ]
#include <gelf.h>

\fBlong\fR \fBgelf_checksum\fR(\fBElf *\fR\fIelf\fR);
.fi

.LP
.nf
\fBsize_t\fR \fBgelf_fsize\fR(\fBElf *\fR\fIelf\fR, \fBElf_Type\fR \fItype\fR, \fBsize_t\fR \fIcnt\fR, \fBunsigned\fR \fIver\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_getcap\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Cap *\fR\fIdst\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_getclass\fR(\fBElf *\fR\fIelf\fR);
.fi

.LP
.nf
\fBGElf_Dyn *\fR\fBgelf_getdyn\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Dyn *\fR\fIdst\fR);
.fi

.LP
.nf
\fBGElf_Ehdr *\fR\fBgelf_getehdr\fR(\fBElf *\fR\fIelf\fR, \fBGElf_Ehdr *\fR\fIdst\fR);
.fi

.LP
.nf
\fBGElf_Move *\fR\fBgelf_getmove\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Move *\fR\fIdst\fR);
.fi

.LP
.nf
\fBGElf_Phdr *\fR\fBgelf_getphdr\fR(\fBElf *\fR\fIelf\fR, \fBint\fR \fIndx\fR, \fBGElf_Phdr *\fR\fIdst\fR);
.fi

.LP
.nf
\fBGElf_Rel *\fR\fBgelf_getrel\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Rel *\fR\fIdst\fR);
.fi

.LP
.nf
\fBGElf_Rela *\fR\fBgelf_getrela\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Rela *\fR\fIdst\fR);
.fi

.LP
.nf
\fBGElf_Shdr *\fR\fBgelf_getshdr\fR(\fBElf_Scn *\fR\fIscn\fR, \fBGElf_Shdr *\fR\fIdst\fR);
.fi

.LP
.nf
\fBGElf_Sym *\fR\fBgelf_getsym\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Sym *\fR\fIdst\fR);
.fi

.LP
.nf
\fBGElf_Syminfo *\fR\fBgelf_getsyminfo\fR(\fBElf_Data *\fR\fIsrc\fR, \fBint\fR \fIndx\fR, \fBGElf_Syminfo *\fR\fIdst\fR);
.fi

.LP
.nf
\fBGElf_Sym *\fR\fBgelf_getsymshndx\fR(\fBElf_Data *\fR\fIsymsrc\fR, \fBElf_Data *\fR\fIshndxsrc\fR,
     \fBint\fR \fIndx\fR, \fBGElf_Sym *\fR\fIsymdst\fR, \fBElf32_Word *\fR\fIshndxdst\fR);
.fi

.LP
.nf
\fBunsigned long\fR \fBgelf_newehdr\fR(\fBElf *\fR\fIelf\fR, \fBint\fR \fIclass\fR);
.fi

.LP
.nf
\fBunsigned long\fR \fBgelf_newphdr\fR(\fBElf *\fR\fIelf\fR, \fBsize_t\fR \fIphnum\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_update_cap\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Cap *\fR\fIsrc\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_update_dyn\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Dyn *\fR\fIsrc\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_update_ehdr\fR(\fBElf *\fR\fIelf\fR, \fBGElf_Ehdr *\fR\fIsrc\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_update_move\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Move *\fR\fIsrc\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_update_phdr\fR(\fBElf *\fR\fIelf\fR, \fBint\fR \fIndx\fR, \fBGElf_Phdr *\fR\fIsrc\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_update_rel\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Rel *\fR\fIsrc\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_update_rela\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Rela *\fR\fIsrc\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_update_shdr\fR(\fBElf_Scn *\fR\fIdst\fR, \fBGElf_Shdr *\fR\fIsrc\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_update_sym\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Sym *\fR\fIsrc\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_update_syminfo\fR(\fBElf_Data *\fR\fIdst\fR, \fBint\fR \fIndx\fR, \fBGElf_Syminfo *\fR\fIsrc\fR);
.fi

.LP
.nf
\fBint\fR \fBgelf_update_symshndx\fR(\fBElf_Data *\fR\fIsymdst\fR, \fBElf_Data *\fR\fIshndxdst\fR, \fBint\fR \fIndx\fR,
     \fBGElf_Sym *\fR\fIsymsrc\fR, \fBElf32_Word\fR \fIshndxsrc\fR);
.fi

.LP
.nf
\fBElf_Data *\fR\fBgelf_xlatetof\fR(\fBElf *\fR\fIelf\fR, \fBElf_Data *\fR\fIdst\fR, \fBconst Elf_Data *\fR\fIsrc\fR,
     \fBunsigned\fR \fIencode\fR);
.fi

.LP
.nf
\fBElf_Data *\fR\fBgelf_xlatetom\fR(\fBElf *\fR\fIelf\fR, \fBElf_Data *\fR\fIdst\fR, \fBconst Elf_Data *\fR\fIsrc\fR,
     \fBunsigned\fR \fIencode\fR);
.fi

.SH DESCRIPTION
.sp
.LP
\fBGElf\fR is a generic, \fBELF\fR class-independent \fBAPI\fR for manipulating
\fBELF\fR object files. \fBGElf\fR provides a single, common interface for
handling 32-bit and 64-bit \fBELF\fR format object files. \fBGElf\fR is a
translation layer between the application and the class-dependent parts of the
\fBELF\fR library. Thus, the application can use \fBGElf\fR, which in turn,
will call the corresponding \fBelf32_\fR or \fBelf64_\fR functions on behalf of
the application. The data structures returned are all large enough to hold
32-bit and 64-bit data.
.sp
.LP
\fBGElf\fR provides a simple, class-independent layer of indirection over the
class-dependent \fBELF32\fR and \fBELF64\fR \fBAPI\fR's. \fBGElf\fR is
stateless, and may be used along side the \fBELF32\fR and \fBELF64\fR
\fBAPI\fR's.
.sp
.LP
\fBGElf\fR always returns a copy of the underlying \fBELF32\fR or \fBELF64\fR
structure, and therefore the programming practice of using the address of an
\fBELF\fR header as the base offset for the \fBELF\fR's mapping into memory
should be avoided. Also, data accessed by type-casting the \fBElf_Data\fR
buffer to a class-dependent type and treating it like an array, for example, a
symbol table, will not work under \fBGElf\fR, and the \fBgelf_get\fR functions
must be used instead. See the EXAMPLE section.
.sp
.LP
Programs that create or modify \fBELF\fR files using \fBlibelf\fR(3LIB) need to
perform an extra step when using \fBGElf\fR. Modifications to \fBGElf\fR values
must be explicitly flushed to the underlying \fBELF32\fR or \fBELF64\fR
structures by way of the \fBgelf_update_\fR interfaces. Use of \fBelf_update\fR
or \fBelf_flagelf\fR and the like remains the same.
.sp
.LP
The sizes of versioning structures remain the same between \fBELF32\fR and
\fBELF64\fR. The \fBGElf\fR \fBAPI\fR only defines types for versioning, rather
than a functional \fBAPI\fR. The processing of versioning information will stay
the same in the \fBGElf\fR environment as it was in the class-dependent
\fBELF\fR environment.
.SS "List of Functions"
.sp
.ne 2
.mk
.na
\fB\fBgelf_checksum()\fR\fR
.ad
.RS 26n
.rt  
An analog to \fBelf32_checksum\fR(3ELF) and \fBelf64_checksum\fR(3ELF).
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_fsize()\fR\fR
.ad
.RS 26n
.rt  
An analog to \fBelf32_fsize\fR(3ELF) and \fBelf64_fsize\fR(3ELF).
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getcap()\fR\fR
.ad
.RS 26n
.rt  
Retrieves the \fBElf32_Cap\fR or \fBElf64_Cap\fR information from the
capability table at the given index. \fBdst\fR points to the location where the
\fBGElf_Cap\fR capability entry is stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getclass()\fR\fR
.ad
.RS 26n
.rt  
Returns one of the constants \fBELFCLASS32\fR, \fBELFCLASS64\fR or
\fBELFCLASSNONE\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getdyn()\fR\fR
.ad
.RS 26n
.rt  
Retrieves the \fBElf32_Dyn\fR or \fBElf64_Dyn\fR information from the dynamic
table at the given index. \fBdst\fR points to the location where the
\fBGElf_Dyn\fR dynamic entry is stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getehdr()\fR\fR
.ad
.RS 26n
.rt  
An analog to \fBelf32_getehdr\fR(3ELF) and \fBelf64_getehdr\fR(3ELF). \fBdst\fR
points to the location where the \fBGElf_Ehdr\fR header is stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getmove()\fR\fR
.ad
.RS 26n
.rt  
Retrieves the \fBElf32_Move\fR or \fBElf64_Move\fR information from the move
table at the given index. \fBdst\fR points to the location where the
\fBGElf_Move\fR move entry is stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getphdr()\fR\fR
.ad
.RS 26n
.rt  
An analog to\fBelf32_getphdr\fR(3ELF) and \fBelf64_getphdr\fR(3ELF). \fBdst\fR
points to the location where the \fBGElf_Phdr\fR program header is stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getrel()\fR\fR
.ad
.RS 26n
.rt  
Retrieves the \fBElf32_Rel\fR or \fBElf64_Rel\fR information from the
relocation table at the given index. \fBdst\fR points to the location where the
\fBGElf_Rel\fR relocation entry is stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getrela()\fR\fR
.ad
.RS 26n
.rt  
Retrieves the \fBElf32_Rela\fR or \fBElf64_Rela\fR information from the
relocation table at the given index. \fBdst\fR points to the location where the
\fBGElf_Rela\fR relocation entry is stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getshdr()\fR\fR
.ad
.RS 26n
.rt  
An analog to \fBelf32_getshdr\fR(3ELF) and \fBelf64_getshdr\fR(3ELF). \fBdst\fR
points to the location where the \fBGElf_Shdr\fR section header is stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getsym()\fR\fR
.ad
.RS 26n
.rt  
Retrieves the \fBElf32_Sym\fR or \fBElf64_Sym\fR information from the symbol
table at the given index. \fBdst\fR points to the location where the
\fBGElf_Sym\fR symbol entry is stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getsyminfo()\fR\fR
.ad
.RS 26n
.rt  
Retrieves the \fBElf32_Syminfo\fR or \fBElf64_Syminfo\fR information from the
relocation table at the given index. \fBdst\fR points to the location where the
\fBGElf_Syminfo\fR symbol information entry is stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_getsymshndx()\fR\fR
.ad
.RS 26n
.rt  
Provides an extension to \fBgelf_getsym()\fR that retrieves the \fBElf32_Sym\fR
or \fBElf64_Sym\fR information, and the section index from the symbol table at
the given index \fIndx\fR.
.sp
The symbols section index is typically recorded in the \fBst_shndx\fR field of
the symbols structure. However, a file that requires \fBELF\fR Extended
Sections may record an \fBst_shndx\fR of \fBSHN_XINDEX\fR indicating that the
section index must be obtained from an associated \fBSHT_SYMTAB_SHNDX\fR
section entry. If \fIxshndx\fR and \fIshndxdata\fR are non-null, the value
recorded at index \fIndx\fR of the \fBSHT_SYMTAB_SHNDX\fR table pointed to by
\fIshndxdata\fR is returned in \fIxshndx\fR. See USAGE.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_newehdr()\fR\fR
.ad
.RS 26n
.rt  
An analog to \fBelf32_newehdr\fR(3ELF) and \fBelf64_newehdr\fR(3ELF).
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_newphdr()\fR\fR
.ad
.RS 26n
.rt  
An analog to \fBelf32_newphdr\fR(3ELF) and \fBelf64_newphdr\fR(3ELF).
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_update_cap()\fR\fR
.ad
.RS 26n
.rt  
Copies the \fBGElf_Cap\fR information back into the underlying \fBElf32_Cap\fR
or \fBElf64_Cap\fR structure at the given index.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_update_dyn()\fR\fR
.ad
.RS 26n
.rt  
Copies the \fBGElf_Dyn\fR information back into the underlying \fBElf32_Dyn\fR
or \fBElf64_Dyn\fR structure at the given index.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_update_ehdr()\fR\fR
.ad
.RS 26n
.rt  
Copies the contents of the \fBGElf_Ehdr\fR \fBELF\fR header to the underlying
\fBElf32_Ehdr\fR or \fBElf64_Ehdr\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_update_move()\fR\fR
.ad
.RS 26n
.rt  
Copies the \fBGElf_Move\fR information back into the underlying
\fBElf32_Move\fR or \fBElf64_Move\fR structure at the given index.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_update_phdr()\fR\fR
.ad
.RS 26n
.rt  
Copies of the contents of \fBGElf_Phdr\fR program header to underlying the
\fBElf32_Phdr\fR or \fBElf64_Phdr\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_update_rel()\fR\fR
.ad
.RS 26n
.rt  
Copies the \fBGElf_Rel\fR information back into the underlying \fBElf32_Rel\fR
or \fBElf64_Rel\fR structure at the given index.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_update_rela()\fR\fR
.ad
.RS 26n
.rt  
Copies the \fBGElf_Rela\fR information back into the underlying
\fBElf32_Rela\fR or \fBElf64_Rela\fR structure at the given index.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_update_shdr()\fR\fR
.ad
.RS 26n
.rt  
Copies of the contents of \fBGElf_Shdr\fR section header to underlying the
\fBElf32_Shdr\fR or \fBElf64_Shdr\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_update_sym()\fR\fR
.ad
.RS 26n
.rt  
Copies the \fBGElf_Sym\fR information back into the underlying \fBElf32_Sym\fR
or \fBElf64_Sym\fR structure at the given index.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_update_syminfo()\fR\fR
.ad
.RS 26n
.rt  
Copies the \fBGElf_Syminfo\fR information back into the underlying
\fBElf32_Syminfo\fR or \fBElf64_Syminfo\fR structure at the given index.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_update_symshndx()\fR\fR
.ad
.RS 26n
.rt  
Provides an extension to \fBgelf_update_sym()\fR that copies the \fBGElf_Sym\fR
information back into the \fBElf32_Sym\fR or \fBElf64_Sym\fR structure at the
given index \fIndx\fR, and copies the extended \fIxshndx\fR section index into
the \fBElf32_Word\fR at the given index \fIndx\fR in the buffer described by
\fBshndxdata\fR. See USAGE.
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_xlatetof()\fR\fR
.ad
.RS 26n
.rt  
An analog to \fBelf32_xlatetof\fR(3ELF) and \fBelf64_xlatetof\fR(3ELF)
.RE

.sp
.ne 2
.mk
.na
\fB\fBgelf_xlatetom()\fR\fR
.ad
.RS 26n
.rt  
An analog to \fBelf32_xlatetom\fR(3ELF) and \fBelf64_xlatetom\fR(3ELF)
.RE

.SH RETURN VALUES
.sp
.LP
Upon failure, all \fBGElf\fR functions return \fB0\fR and set \fIelf_errno\fR.
See \fBelf_errno\fR(3ELF)
.SH EXAMPLES
.LP
\fBExample 1 \fRPrinting the ELF Symbol Table
.sp
.in +2
.nf
#include <stdio.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <libelf.h>
#include <gelf.h>

void
main(int argc, char **argv)
{
    Elf         *elf;
    Elf_Scn     *scn = NULL;
    GElf_Shdr   shdr;
    Elf_Data    *data;
    int         fd, ii, count;

    elf_version(EV_CURRENT);

    fd = open(argv[1], O_RDONLY);
    elf = elf_begin(fd, ELF_C_READ, NULL);

    while ((scn = elf_nextscn(elf, scn)) != NULL) {
        gelf_getshdr(scn, &shdr);
        if (shdr.sh_type == SHT_SYMTAB) {
            /* found a symbol table, go print it. */
            break;
        }
    }

    data = elf_getdata(scn, NULL);
    count = shdr.sh_size / shdr.sh_entsize;

    /* print the symbol names */
    for (ii = 0; ii < count; ++ii) {
        GElf_Sym sym;
        gelf_getsym(data, ii, &sym);
        printf("%s\en", elf_strptr(elf, shdr.sh_link, sym.st_name));
    }
    elf_end(elf);
    close(fd);
}
.fi
.in -2

.SH USAGE
.sp
.LP
ELF Extended Sections are employed to allow an ELF file to contain more than
\fB0xff00\fR (\fBSHN_LORESERVE\fR) section. See the \fILinker and Libraries
Guide\fR for more information.
.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/lib/libelf.so.1\fR\fR
.ad
.RS 23n
.rt  
shared object
.RE

.sp
.ne 2
.mk
.na
\fB\fB/lib/64/libelf.so.1\fR\fR
.ad
.RS 23n
.rt  
64-bit shared object
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityStable
_
MT LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBelf\fR(3ELF), \fBelf32_checksum\fR(3ELF), \fBelf32_fsize\fR(3ELF),
\fBelf32_getehdr\fR(3ELF), \fBelf32_newehdr\fR(3ELF),
\fBelf32_getphdr\fR(3ELF), \fBelf32_newphdr\fR(3ELF),
\fBelf32_getshdr\fR(3ELF), \fBelf32_xlatetof\fR(3ELF),
\fBelf32_xlatetom\fR(3ELF), \fBelf_errno\fR(3ELF), \fBlibelf\fR(3LIB),
\fBattributes\fR(5)
.sp
.LP
\fILinker and Libraries Guide\fR