.\" 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 2825 2012-12-29 14:25:33Z jkoshy $
.\"
.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 occured 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