Tribblix: manual page: Psymbol

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