PSYMBOL_ITER(3PROC) Process Control Library Functions PSYMBOL_ITER(3PROC)
NAME
Psymbol_iter,
Psymbol_iter_by_addr,
Psymbol_iter_by_lmid,
Psymbol_iter_by_name,
Pxsymbol_iter - iterate symbols in a process
LIBRARY
Process Control Library (libproc, -lproc)
SYNOPSIS
#include <libproc.h> int Psymbol_iter(
struct ps_prochandle *P,
const char *object_name,
int which,
int mask,
proc_sym_f *func,
void *data);
int Psymbol_iter_by_addr(
struct ps_prochandle *P,
const char *object_name,
int which,
int mask,
proc_sym_f *func,
void *data);
int Psymbol_iter_by_lmid(
struct ps_prochandle *P,
Lmid_t lmid,
const char *object_name,
int which,
int mask,
proc_sym_f *func,
void *data);
int Psymbol_iter_by_name(
struct ps_prochandle *P,
const char *object_name,
int which,
int mask,
proc_sym_f *func,
void *data);
int Pxsymbol_iter(
struct ps_prochandle *P,
Lmid_t lmid,
const char *object_name,
int which,
int mask,
proc_xsym_f *func,
void *data);
DESCRIPTION
The
Psymbol_iter(),
Psymbol_iter_by_addr(),
Psymbol_iter_by_lmid(),
Psymbol_iter_by_name(), and
Pxsymbol_iter() functions are used to iterate
over the symbols present in the process referred to by the handle
P. For
each symbol found, the callback function
func will be called once and the
argument
data will be passed to it along with an ELF symbol entry in the
form of the
GElf_Sym along with the name of the symbol, if known. In the
case of the
Pxsymbol_iter() function an additional
prsyminfo_t argument
will be provided to the callback. The definitions of
proc_sym_f,
proc_xsym_f, and
prsyminfo_t are found in
libproc(3LIB).
The
object_name argument names the object that is a part of the controlled
process which will be searched for symbols. Only one object may be
searched at any given time. Valid object names may be obtained through the
Pobjname(3PROC) and
Pobject_iter(3PROC) functions, among others. The
system also has two special object names that may be passed in to refer to
the objects of the executable file and for ld.so.1. The symbol PR_OBJ_EXEC
refers to the executables object and the symbol PR_OBJ_LDSO refers to the
object ld.so.1.
The
which argument controls which of two possible symbol tables will be
searched. If the argument is PR_SYMTAB then the ELF symbol table will be
searched. Otherwise, if it is PR_DYNSYM then the symbol table associated
with the dynamic section will be searched instead. If any other value is
specified for
which, then an error will be returned.
The
mask argument controls which symbols will be included. The
mask argument allows for control over both the symbol's binding and the symbol's
type. These flags logically correspond to the various ELF symbol bindings
and types. The following values may be passed as a bitwise-inclusive-OR
into the
flags argument:
BIND_LOCAL The symbol is a local symbol. Local symbols are not
visible outside of their object file.
BIND_GLOBAL The symbol is a global symbol. Global symbols are
visible outside of their object file and may be
referred to by other ELF objects.
BIND_WEAK The symbol is a weak symbol. Weak symbols are visible
outside of their object file, but another definition of
the symbol may be used instead.
BIND_ANY This is a combination of BIND_LOCAL, BIND_GLOBAL, and
BIND_WEAK. Every symbol's binding will match this
value.
TYPE_NOTYPE The symbol's type is not specified.
TYPE_OBJECT The symbol refers to a data object. For example,
variables.
TYPE_FUNC The symbol refers to a function.
TYPE_SECTION The symbol refers to an ELF section.
TYPE_FILE The symbol refers to the name of a source file
associated with an object file.
TYPE_ANY This is a combination of TYPE_NOTYPE, TYPE_OBJECT,
TYPE_FUNC, TYPE_SECTION, and TYPE_FILE. Every symbol's
type will match this value.
To obtain all of the symbols in an object, the caller would pass the
expression BIND_ANY | TYPE_ANY in as the value of
mask. The
Psymbol_iter_by_lmid() and
Pxsymbol_iter() functions allow for a link-
map identifier to be specified in the
lmid argument. This will restrict
the search for the object specified in
object_name to the specified link-
map. There are three special link-map identifiers that may be passed in.
The symbol PR_LMID_EVERY indicates that every link-map should be searched.
The symbol LM_ID_BASE indicates that the base link-map, the one that is
used for the executable should be searched. Finally, the symbol LM_ID_LDSO
refers to the link-map that is used by the run-time link editor, ld.so.1.
The functions which do not allow a link-map identifier to be specified
always search every link-map.
By default, symbols are iterated based on the order of the symbol table
being searched. However, it is also possible to iterate based on the name
of the symbol and based on the address of the symbol. To iterate by name
use the
Psymbol_iter_by_name() function. To iterate by address use the
Psymbol_iter_by_addr() function. The
Psymbol_iter(),
Psymbol_iter_by_lmid(), and
Pxsymbol_iter() functions all sort based on the
order of the symbol table.
The return value of the callback function
func determines whether or not
iteration continues. If
func returns
0, then iteration will continue.
However, if
func returns non-zero, then iteration will halt and that value
will be used as the return value of the
Psymbol_iter(),
Psymbol_iter_by_addr(),
Psymbol_iter_by_lmid(),
Psymbol_iter_by_name(), and
Pxsymbol_iter() functions. Because these functions return
-1 on internal
failure, it is recommended that the callback function not return
-1 to
indicate an error so that the caller may distinguish between the failure of
the callback function and the failure of these functions.
RETURN VALUES
Upon successful completion, the
Psymbol_iter(),
Psymbol_iter_by_addr(),
Psymbol_iter_by_lmid(),
Psymbol_iter_by_name(), and
Pxsymbol_iter()
functions return
0. If there was an internal error then
-1 is returned.
Otherwise, if the callback function
func returns non-zero, then its return
value will be returned instead.
INTERFACE STABILITY
UncommittedMT-LEVEL See
LOCKING in
libproc(3LIB).
SEE ALSO
elf(3ELF),
gelf(3ELF),
libproc(3LIB),
proc(5)illumos May 11, 2016 illumos