a4c24f2588
Highlights: - Fix man page markup, whitespace, and typos - Fix sh_info of SHT_GROUP section to point to the correct string - Improve validation in readelf and elfcopy/strip - Handle DWARF 4's DW_AT_high_pc in addr2line Sponsored by: The FreeBSD Foundation
530 lines
14 KiB
Groff
530 lines
14 KiB
Groff
.\" Copyright (c) 2012 Joseph Koshy. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" This software is provided by Joseph Koshy ``as is'' and
|
|
.\" any express or implied warranties, including, but not limited to, the
|
|
.\" implied warranties of merchantability and fitness for a particular purpose
|
|
.\" are disclaimed. in no event shall Joseph Koshy be liable
|
|
.\" for any direct, indirect, incidental, special, exemplary, or consequential
|
|
.\" damages (including, but not limited to, procurement of substitute goods
|
|
.\" or services; loss of use, data, or profits; or business interruption)
|
|
.\" however caused and on any theory of liability, whether in contract, strict
|
|
.\" liability, or tort (including negligence or otherwise) arising in any way
|
|
.\" out of the use of this software, even if advised of the possibility of
|
|
.\" such damage.
|
|
.\"
|
|
.\" $Id: elftc_symbol_table_create.3 3182 2015-04-10 16:08:10Z emaste $
|
|
.\"
|
|
.Dd December 29, 2012
|
|
.Os
|
|
.Dt ELFTC_SYMBOL_TABLE_CREATE 3
|
|
.Sh NAME
|
|
.Nm elftc_elf_symbol_table_from_section ,
|
|
.Nm elftc_symbol_table_count ,
|
|
.Nm elftc_symbol_table_create ,
|
|
.Nm elftc_symbol_table_create_nested ,
|
|
.Nm elftc_symbol_table_delete_name ,
|
|
.Nm elftc_symbol_table_delete_entry ,
|
|
.Nm elftc_symbol_table_destroy ,
|
|
.Nm elftc_symbol_table_insert ,
|
|
.Nm elftc_symbol_table_iterate ,
|
|
.Nm elftc_symbol_table_lookup ,
|
|
.Nm elftc_symbol_table_lookup_value ,
|
|
.Nm elftc_symbol_table_replace ,
|
|
.Nm elftc_symbol_table_sort ,
|
|
.Nm elftc_symbol_table_step
|
|
.Nd symbol table management routines
|
|
.Sh SYNOPSIS
|
|
.In libelftc.h
|
|
.Bd -literal
|
|
typedef struct _Elftc_Symbol_Table Elftc_Symbol_Table;
|
|
|
|
typedef struct _Elftc_Symbol {
|
|
... library private fields ...
|
|
const char *sym_name;
|
|
uintptr_t sym_value;
|
|
} Elftc_Symbol;
|
|
.Ed
|
|
.Ft size_t
|
|
.Fn elftc_symbol_table_count "Elftc_Symbol_Table *table"
|
|
.Ft "Elftc_Symbol_Table *"
|
|
.Fo elftc_symbol_table_create
|
|
.Fa "size_t entrysize"
|
|
.Fa "int sizehint"
|
|
.Fc
|
|
.Ft "Elftc_Symbol_Table *"
|
|
.Fo elftc_symbol_table_create_nested
|
|
.Fa "Elftc_Symbol_Table *table"
|
|
.Fa "int sizehint"
|
|
.Fc
|
|
.Ft int
|
|
.Fo elftc_symbol_table_delete_name
|
|
.Fa "Elftc_Symbol_Table *table"
|
|
.Fa "const char *name"
|
|
.Fc
|
|
.Ft int
|
|
.Fo elftc_symbol_table_delete_entry
|
|
.Fa "Elftc_Symbol_Table *table"
|
|
.Fa "Elftc_Symbol *entry"
|
|
.Fc
|
|
.Ft int
|
|
.Fn elftc_symbol_table_destroy "Elftc_Symbol_Table *table"
|
|
.Ft "Elftc_Symbol *entry"
|
|
.Fo elftc_symbol_table_insert
|
|
.Fa "Elftc_Symbol_Table *table"
|
|
.Fa "const char *symbolname"
|
|
.Fa "int *status"
|
|
.Fc
|
|
.Ft int
|
|
.Fo elftc_symbol_table_iterate
|
|
.Fa "Elftc_Symbol_Table *table"
|
|
.Fa "int (*iterfn)(Elftc_Symbol *entry, void *cookie)"
|
|
.Fa "void *cookie"
|
|
.Fc
|
|
.Ft "Elftc_Symbol *"
|
|
.Fo elftc_symbol_table_lookup
|
|
.Fa "Elftc_Symbol_Table *table"
|
|
.Fa "const char *symbolname"
|
|
.Fc
|
|
.Ft "Elftc_Elf_Symbol *"
|
|
.Fo elftc_symbol_table_lookup_value
|
|
.Fa "Elftc_Symbol_Table *table"
|
|
.Fa "uintptr_t value"
|
|
.Fa "int searchflags"
|
|
.Fc
|
|
.Ft int
|
|
.Fo elftc_symbol_table_replace
|
|
.Fa "Elftc_Symbol_Table *table"
|
|
.Fa "Elftc_Symbol *sym1"
|
|
.Fa "Elftc_Symbol *sym2"
|
|
.Fc
|
|
.Ft int
|
|
.Fo elftc_symbol_table_sort
|
|
.Fa "Elftc_Symbol_Table *table"
|
|
.Fa "int (*cmpfn)(Elftc_Symbol *s1, Elftc_Symbol *s2)"
|
|
.Fc
|
|
.Ft "Elftc_Symbol *"
|
|
.Fo elftc_symbol_table_step
|
|
.Fa "Elftc_Symbol_Table *table"
|
|
.Fa "Elftc_Symbol *cursym"
|
|
.Fa "int direction"
|
|
.Fc
|
|
.Bd -literal
|
|
typedef struct _Elftc_Elf_Symbol {
|
|
... library private fields ...
|
|
const char *sym_name;
|
|
Gelf_Sym sym_elf;
|
|
} Elftc_Elf_Symbol;
|
|
.Ed
|
|
.Ft "Elftc_Symbol_Table *"
|
|
.Fo elftc_elf_symbol_table_from_section
|
|
.Fa "Elf_Scn *symscn"
|
|
.Fa "Elf_Scn *strscn"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
This manual page documents convenience routines for handling symbol
|
|
tables.
|
|
Two flavors of symbol tables are supported:
|
|
.Bl -bullet -compact
|
|
.It
|
|
.Dq Regular
|
|
symbol tables supporting insertion, deletion and lookup of entries by
|
|
name or by value, sorting of entries, and stepping through entries in
|
|
the table's current traversal order.
|
|
.It
|
|
.Dq ELF-centric
|
|
symbol tables support additional operations for conversions to and
|
|
from the symbol table format understood by
|
|
.Lb libelf .
|
|
.El
|
|
The default traversal order for a symbol table is the order in which
|
|
entries were inserted into it.
|
|
This traversal order may be changed using function
|
|
.Fn elftc_symbol_table_sort .
|
|
.Ss Operations on Regular Symbol Tables
|
|
Regular symbol tables use symbols that are subtypes of
|
|
.Vt Elftc_Symbol ,
|
|
as described in the section
|
|
.Sx "Structure of a Symbol Table Entry"
|
|
below.
|
|
.Pp
|
|
Function
|
|
.Fn elftc_symbol_table_count
|
|
returns the number of entries currently in the symbol table.
|
|
.Pp
|
|
Function
|
|
.Fn elftc_symbol_table_create
|
|
creates a new, empty symbol table.
|
|
The argument
|
|
.Ar entrysize
|
|
specifies the size of each symbol table entry, as described
|
|
in the section
|
|
.Sx "Structure of a Symbol Table Entry"
|
|
below.
|
|
The argument
|
|
.Ar sizehint
|
|
specifies the expected number of symbol table entries.
|
|
If
|
|
.Ar sizehint
|
|
is zero, an implementation-defined default will be used.
|
|
.Pp
|
|
Function
|
|
.Fn elftc_symbol_table_create_nested
|
|
creates a symbol table whose search scope nests inside that of a
|
|
parent symbol table.
|
|
The argument
|
|
.Ar parent
|
|
specifies the parent symbol table to nest under.
|
|
The argument
|
|
.Ar sizehint
|
|
specifies the expected number of symbol table entries.
|
|
If
|
|
.Ar sizehint
|
|
is zero, an implementation-defined default will be used instead.
|
|
.Pp
|
|
The function
|
|
.Fn elftc_symbol_table_delete_name
|
|
removes the symbol entry named by the argument
|
|
.Ar name
|
|
from the symbol table specified by argument
|
|
.Ar table ,
|
|
according to the rules described in section
|
|
.Sx "Symbol Search Rules" .
|
|
.Pp
|
|
The function
|
|
.Fn elftc_symbol_table_delete_entry
|
|
removes the symbol table entry specified by argument
|
|
.Ar entry
|
|
from the symbol table specified by argument
|
|
.Ar table .
|
|
.Pp
|
|
Function
|
|
.Fn elftc_symbol_table_destroy
|
|
is used to destroy a symbol table and free up its internal
|
|
resources.
|
|
.Pp
|
|
The function
|
|
.Fn elftc_symbol_table_insert
|
|
inserts a symbol entry for the name specified by argument
|
|
.Ar symbolname
|
|
into the symbol table specified by argument
|
|
.Ar table ,
|
|
returning a pointer to a symbol table entry.
|
|
The argument
|
|
.Ar status
|
|
should point to a location that will be updated with one of
|
|
the following values:
|
|
.Bl -tag -width indent -compact -offset indent
|
|
.It Dv ELFTC_INSERT_ERROR
|
|
An error occurred during insertion of the symbol.
|
|
.It Dv ELFTC_INSERT_EXISTING
|
|
The name in argument
|
|
.Ar symbolname
|
|
was already in the symbol table, and a pointer to the existing
|
|
symbol table entry is being returned.
|
|
.It Dv ELFTC_INSERT_NEW
|
|
A new symbol table entry was allocated for the symbol name
|
|
in
|
|
.Ar symbolname .
|
|
The application will need to initialize the application-specific
|
|
fields of the symbol table entry.
|
|
.El
|
|
Insertion obeys the scoping rules described in section
|
|
.Sx "Symbol Search Rules" .
|
|
.Pp
|
|
The function
|
|
.Fn elftc_symbol_table_iterate
|
|
iterates over the symbol table specifed by argument
|
|
.Ar table ,
|
|
applying the function pointed to by argument
|
|
.Ar iterfn
|
|
to each symbol table entry.
|
|
The return value from the function
|
|
.Ar iterfn
|
|
controls progress of the iteration:
|
|
.Bl -tag -width indent -compact -offset indent
|
|
.It Dv ELFTC_ITERATE_ABORT
|
|
Terminates the iteration.
|
|
.It Dv ELFTC_ITERATE_CONTINUE
|
|
Iteration will continue on to the next element in the symbol table.
|
|
.El
|
|
Argument
|
|
.Ar cookie
|
|
will be passed to each invocation of
|
|
.Ar iterfn ,
|
|
and may be used to track persistent state.
|
|
The ordering of symbol table entries presented to function
|
|
.Ar iterfn
|
|
is not defined.
|
|
The behavior of the iteration is undefined if
|
|
.Ar iterfn
|
|
adds or deletes symbol entries from a symbol table that currently
|
|
being iterated through.
|
|
.Pp
|
|
Function
|
|
.Fn elftc_symbol_table_lookup
|
|
returns the symbol entry corresponding to the name of the symbol
|
|
in argument
|
|
.Ar symbolname .
|
|
.Pp
|
|
Function
|
|
.Fn elftc_symbol_table_lookup_value
|
|
returns the symbol entry that has a
|
|
.Va sym_value
|
|
field that is closest to the value specified in argument
|
|
.Ar value .
|
|
The argument
|
|
.Ar table
|
|
should point to a symbol table, that has been sorted
|
|
by a prior call to
|
|
.Fn elftc_symbol_table_sort .
|
|
The argument
|
|
.Ar searchflags
|
|
can be a combination of the following flags:
|
|
.Bl -tag -width indent -compact -offset indent
|
|
.It Dv ELFTC_SEARCH_FORWARD
|
|
Find the symbol entry with the next higher value in its
|
|
.Va sym_value
|
|
field.
|
|
.It Dv ELFTC_SEARCH_BACKWARD
|
|
Find the symbol entry with next lower value in its
|
|
.Va sym_value
|
|
field.
|
|
.El
|
|
If both
|
|
.Dv ELFTC_SEARCH_FORWARD
|
|
and
|
|
.Dv ELFTC_SEARCH_BACKWARD
|
|
are specified, then this function will return the symbol that is
|
|
closest to the argument
|
|
.Ar value .
|
|
.Pp
|
|
Function
|
|
.Fn elftc_symbol_table_replace
|
|
moves the symbol table entry pointed to by argument
|
|
.Ar sym2
|
|
into the traversal position for the entry pointed to by
|
|
.Ar sym1 ,
|
|
and implicitly deletes the entry pointed to by argument
|
|
.Ar sym1 .
|
|
Argument
|
|
.Ar table
|
|
should point to a valid symbol table.
|
|
.Pp
|
|
Function
|
|
.Fn elftc_symbol_table_sort
|
|
is used to define an ordering of symbol entries in a symbol
|
|
table.
|
|
This ordering will be associated with the symbol table till the next
|
|
call to function
|
|
.Fn elftc_symbol_table_insert ,
|
|
.Fn elftc_symbol_table_delete_name
|
|
or
|
|
.Fn elftc_symbol_table_delete_entry .
|
|
The argument
|
|
.Ar cmpfn
|
|
should point to a function that compares two symbol entries pointed
|
|
to by
|
|
.Ar s1
|
|
and
|
|
.Ar s2
|
|
and returns -1, 0, or 1, depending whether
|
|
.Ar s1
|
|
is less, equal to, or greater than
|
|
.Ar s2
|
|
respectively.
|
|
.Pp
|
|
Function
|
|
.Fn elftc_symbol_table_step
|
|
is used to step to the next symbol in a sorted symbol table.
|
|
Argument
|
|
.Ar table
|
|
should point to a symbol table.
|
|
The argument
|
|
.Ar cursym
|
|
specifies the current symbol.
|
|
The argument
|
|
.Ar direction
|
|
specifies the direction to step:
|
|
.Bl -tag -width indent -compact -offset ident
|
|
.It Dv ELFTC_STEP_NEXT
|
|
Return the symbol which follows the argument
|
|
.Ar cursym
|
|
in the current traversal order.
|
|
If argument
|
|
.Ar cursym
|
|
is NULL, return the first symbol in the current
|
|
traversal order.
|
|
.It Dv ELFTC_STEP_PREVIOUS
|
|
Return the symbol which precedes the argument
|
|
.Ar cursym
|
|
in the current traversal order.
|
|
If argument
|
|
.Ar cursym
|
|
is NULL, return the last symbol in the current
|
|
traversal order.
|
|
.El
|
|
.Ss Operations on ELF-centric symbol tables
|
|
ELF-centric symbol tables use symbols that are subtypes of
|
|
.Vt Elftc_Elf_Symbol ,
|
|
as described in the section
|
|
.Sx "Structure of a Symbol Table Entry"
|
|
below.
|
|
.Pp
|
|
In addition to the operations on regular symbol tables listed above,
|
|
these symbol tables may be used with the following additional
|
|
functions.
|
|
.Pp
|
|
The function
|
|
.Fn elftc_elf_symbol_table_from_section
|
|
builds a symbol table from the contents of an ELF section.
|
|
The argument
|
|
.Ar symscn
|
|
should reference an ELF section of type
|
|
.Dv SHT_SYMTAB
|
|
or
|
|
.Dv SHT_DYNSYM .
|
|
The argument
|
|
.Ar strscn
|
|
should reference an ELF section of type
|
|
.Dv SHT_STRTAB
|
|
containing the string table associated wit section
|
|
.Ar symscn .
|
|
.Ss Structure of a Symbol Table Entry
|
|
The symbol tables managed by
|
|
.Lb libelftc
|
|
are collections of symbol table entries.
|
|
Each entry should be a subtype of one of the
|
|
.Vt Elftc_Symbol
|
|
or
|
|
.Vt Elftc_Elf_Symbol
|
|
types.
|
|
In other words, each entry should have an
|
|
.Vt Elftc_Symbol
|
|
or
|
|
.Vt Elftc_Elf_Symbol
|
|
structure as its first member, before any application specific
|
|
fields.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
struct _MySymbol {
|
|
Elftc_Symbol sym_base;
|
|
... other application-specific fields ...
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The size of the combined entry is indicated to the library
|
|
at the time of creating a new symbol table.
|
|
Applications may then cast the returned pointers from these
|
|
routines to the appropriate type:
|
|
.Bd -literal -offset indent
|
|
struct _MySymbol *mysym;
|
|
|
|
mysym = (struct _MySymbol *) elftc_symbol_table_lookup(table,
|
|
name);
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Vt Elftc_Symbol
|
|
type has two public fields:
|
|
.Bl -tag -width ".Va sym_value" -compact -offset indent
|
|
.It Va sym_name
|
|
Points to a NUL-terminated string containing the symbol's name.
|
|
The application should not change the value of this field.
|
|
.It Va sym_value
|
|
The value associated with this symbol.
|
|
This field is entirely under the application's control.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Vt Elftc_Elf_Symbol
|
|
type has two public fields:
|
|
.Bl -tag -width ".Va sym_value" -compact -offset indent
|
|
.It Va sym_name
|
|
Points to a NUL-terminated string containing the symbol's name.
|
|
The application should not change the value of this field.
|
|
.It Va sym_elf
|
|
A structure of type
|
|
.Vt Gelf_Sym
|
|
containing ELF symbol information.
|
|
This field is entirely under the application's control.
|
|
.El
|
|
.Ss Symbol Search Rules
|
|
During lookups, symbols are looked up first in the symbol table passed in
|
|
to the
|
|
.Fn elftc_symbol_table_lookup
|
|
function.
|
|
If the specified symbol is not found, and if the symbol table has a
|
|
parent, then the search continues recursively up the chain of parent
|
|
symbol tables till either a matching symbol is found or till there are
|
|
no more parent symbol tables to search in.
|
|
.Pp
|
|
Insertions and deletion only work on the specified symbol table and
|
|
do not recurse into parent symbol tables.
|
|
.Ss Memory Management
|
|
The
|
|
.Lb libelftc
|
|
manages its memory allocations.
|
|
Applications should not free the pointers returned by the
|
|
API documented in this manual page.
|
|
.Sh RETURN VALUES
|
|
Function
|
|
.Fn elftc_symbol_table_count
|
|
returns a count of the number of symbol table entries as an unsigned
|
|
value.
|
|
.Pp
|
|
Functions
|
|
.Fn elftc_symbol_table_create ,
|
|
.Fn elftc_symbol_table_create_nested
|
|
and
|
|
.Fn elftc_symbol_table_from_section
|
|
return a pointer to an opaque structure of type
|
|
.Vt Elftc_Symbol_Table
|
|
on success, or return NULL in case of an error.
|
|
.Pp
|
|
Functions
|
|
.Fn elftc_symbol_table_delete_name ,
|
|
.Fn elftc_symbol_table_delete_name
|
|
.Fn elftc_symbol_table_destroy ,
|
|
.Fn elftc_symbol_table_replace
|
|
and
|
|
.Fn elftc_symbol_table_sort
|
|
return a non-zero value on success, or return zero in case of an error.
|
|
.Pp
|
|
Functions
|
|
.Fn elftc_symbol_table_insert ,
|
|
.Fn elftc_symbol_table_lookup
|
|
and
|
|
.Fn elftc_symbol_table_lookup_value
|
|
return a pointer to a structure that is a subtype of
|
|
.Vt Elftc_Symbol
|
|
on success, or return NULL in case of an error.
|
|
.Pp
|
|
The function
|
|
.Fn elftc_symbol_table_step
|
|
return a pointer to a structure that is a subtype of
|
|
.Vt Elftc_Symbol
|
|
on success.
|
|
The function returns NULL if there are no more elements in the
|
|
specified traversal direction.
|
|
.Pp
|
|
The function
|
|
.Fn elftc_symbol_table_iterate
|
|
returns
|
|
.Dv ELFTC_ITERATE_SUCCESS
|
|
if the symbol table was successfully traversed, or
|
|
.Dv ELFTC_ITERATE_ABORT
|
|
in case the iteration function aborted the traversal.
|
|
.Sh SEE ALSO
|
|
.Xr dwarf 3 ,
|
|
.Xr elf 3 ,
|
|
.Xr elftc 3
|