path: root/usr/src/man/man3elf/gelf.3elf

'\" 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 "Jun 8, 2004"
.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
.na
\fB\fBgelf_checksum()\fR\fR
.ad
.RS 26n
An analog to \fBelf32_checksum\fR(3ELF) and \fBelf64_checksum\fR(3ELF).
.RE

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

.sp
.ne 2
.na
\fB\fBgelf_getcap()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_getclass()\fR\fR
.ad
.RS 26n
Returns one of the constants \fBELFCLASS32\fR, \fBELFCLASS64\fR or
\fBELFCLASSNONE\fR.
.RE

.sp
.ne 2
.na
\fB\fBgelf_getdyn()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_getehdr()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_getmove()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_getphdr()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_getrel()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_getrela()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_getshdr()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_getsym()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_getsyminfo()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_getsymshndx()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_newehdr()\fR\fR
.ad
.RS 26n
An analog to \fBelf32_newehdr\fR(3ELF) and \fBelf64_newehdr\fR(3ELF).
.RE

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

.sp
.ne 2
.na
\fB\fBgelf_update_cap()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_update_dyn()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_update_ehdr()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_update_move()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_update_phdr()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_update_rel()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_update_rela()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_update_shdr()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_update_sym()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_update_syminfo()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_update_symshndx()\fR\fR
.ad
.RS 26n
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
.na
\fB\fBgelf_xlatetof()\fR\fR
.ad
.RS 26n
An analog to \fBelf32_xlatetof\fR(3ELF) and \fBelf64_xlatetof\fR(3ELF)
.RE

.sp
.ne 2
.na
\fB\fBgelf_xlatetom()\fR\fR
.ad
.RS 26n
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
.na
\fB\fB/lib/libelf.so.1\fR\fR
.ad
.RS 23n
shared object
.RE

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

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

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Stable
_
MT Level	MT-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