Go to main content

man pages section 3: Extended Library Functions, Volume 3

Exit Print View

Updated: Thursday, June 13, 2019
 
 

Psymbol_iter_by_name (3PROC)

Name

Psymbol_iter, Psymbol_iter_by_addr, Psymbol_iter_by_name - walk the symbol tables of a victim process

Synopsis

#include <libproc.h>
typedef int proc_sym_f(void *cd, const GElf_Sym *, const char *);
int Psymbol_iter(ps_prochandle_t *Pr, const char *object_name,
         int which, int mask, proc_sym_f *func, void *cd);
int Psymbol_iter_by_addr(ps_prochandle_t *Pr, const char *object_name,
         int which, int mask, proc_sym_f *func, void *cd);
int Psymbol_iter_by_name(ps_prochandle_t *Pr, const char *object_name,
         int which, int mask, proc_sym_f *func, void *cd);

Description

The Pr argument identifies a victim process or core file attached to the controlling process by the create and grab interfaces. For more information, see the Pcreate(3PROC) and Pgrab(3PROC) man pages.

The Psymbol_iter() function iterates over the symbols from the specified symbol table in natural or unsorted order.

The Psymbol_iter_by_addr() function iterates over the symbols from the specified symbol table in virtual address order.

The Psymbol_iter_by_name() function iterates over the symbols from the specified symbol table in alphabetic order.

The object_name argument names the mapped object containing the symbol table. For example: libc.so.

The which argument must either be:

  • PR_SYMTAB

  • PR_DYNSYM

The mask argument must be a bit-wise OR of one or more of the flags:

  • BIND_LOCAL

  • BIND_GLOBAL

  • BIND_WEAK

The mask argument will also include one or more of the flags:

  • TYPE_NOTYPE

  • TYPE_OBJECT

  • TYPE_FUNC

  • TYPE_SECTION

  • TYPE_FILE

As a programming convenience, BIND_ANY includes all of the BIND_* flags and TYPE_ANY includes all of the TYPE_* flags.

On finding a symbol that meets the criteria specified by which and mask arguments, the specified function is called, and is passed the specified cd argument, a pointer to the symbol table entry, and a pointer to the name string of the symbol which is valid only for the duration of the call. For more information, see the gelf(3ELF) man page.

The iteration is terminated by the first non-zero value returned by the specified function, or by reaching the end of the symbol table.

Return Values

On success, the Psymbol_iter(), Psymbol_iter_by_addr(), and Psymbol_iter_by_name() functions return 0 or the first non-zero value returned by the specified callback function. On failure, such as no mapped object found, they return -1 and do not set errno.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Unsafe

See Also

gelf(3ELF), libproc.h(3HEAD), libproc(3LIB), Pcreate(3PROC), Pgrab(3PROC), proc(5)