Print this page
8158 Want named threads API
9857 proc manpages should have LIBRARY section
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3proc/Psymbol_iter.3proc.man.txt
+++ new/usr/src/man/man3proc/Psymbol_iter.3proc.man.txt
1 1 PSYMBOL_ITER(3PROC) Process Control Library Functions PSYMBOL_ITER(3PROC)
2 2
3 3 NAME
4 4 Psymbol_iter, Psymbol_iter_by_addr, Psymbol_iter_by_lmid,
5 5 Psymbol_iter_by_name, Pxsymbol_iter - iterate symbols in a process
6 6
7 -SYNOPSIS
7 +LIBRARY
8 8 Process Control Library (libproc, -lproc)
9 +
10 +SYNOPSIS
9 11 #include <libproc.h>
10 12
11 13 int
12 14 Psymbol_iter(struct ps_prochandle *P, const char *object_name, int which,
13 15 int mask, proc_sym_f *func, void *data);
14 16
15 17 int
16 18 Psymbol_iter_by_addr(struct ps_prochandle *P, const char *object_name,
17 19 int which, int mask, proc_sym_f *func, void *data);
18 20
19 21 int
20 22 Psymbol_iter_by_lmid(struct ps_prochandle *P, Lmid_t lmid,
21 23 const char *object_name, int which, int mask, proc_sym_f *func,
22 24 void *data);
23 25
24 26 int
25 27 Psymbol_iter_by_name(struct ps_prochandle *P, const char *object_name,
26 28 int which, int mask, proc_sym_f *func, void *data);
27 29
28 30 int
29 31 Pxsymbol_iter(struct ps_prochandle *P, Lmid_t lmid,
30 32 const char *object_name, int which, int mask, proc_xsym_f *func,
31 33 void *data);
32 34
33 35 DESCRIPTION
34 36 The Psymbol_iter(), Psymbol_iter_by_addr(), Psymbol_iter_by_lmid(),
35 37 Psymbol_iter_by_name(), and Pxsymbol_iter() functions are used to iterate
36 38 over the symbols present in the process referred to by the handle P. For
37 39 each symbol found, the callback function func will be called once and the
38 40 argument data will be passed to it along with an ELF symbol entry in the
39 41 form of the GElf_Sym along with the name of the symbol, if known. In the
40 42 case of the Pxsymbol_iter() function an additional prsyminfo_t argument
41 43 will be provided to the callback. The definitions of proc_sym_f,
42 44 proc_xsym_f, and prsyminfo_t are found in libproc(3LIB).
43 45
44 46 The object_name argument names the object that is a part of the
45 47 controlled process which will be searched for symbols. Only one object
46 48 may be searched at any given time. Valid object names may be obtained
47 49 through the Pobjname(3PROC) and Pobject_iter(3PROC) functions, among
48 50 others. The system also has two special object names that may be passed
49 51 in to refer to the objects of the executable file and for ld.so.1. The
50 52 symbol PR_OBJ_EXEC refers to the executables object and the symbol
51 53 PR_OBJ_LDSO refers to the object ld.so.1.
52 54
53 55 The which argument controls which of two possible symbol tables will be
54 56 searched. If the argument is PR_SYMTAB then the ELF symbol table will be
55 57 searched. Otherwise, if it is PR_DYNSYM then the symbol table associated
56 58 with the dynamic section will be searched instead. If any other value is
57 59 specified for which, then an error will be returned.
58 60
59 61 The mask argument controls which symbols will be included. The mask
60 62 argument allows for control over both the symbol's binding and the
61 63 symbol's type. These flags logically correspond to the various ELF
62 64 symbol bindings and types. The following values may be passed as a
63 65 bitwise-inclusive-OR into the flags argument:
64 66
65 67 BIND_LOCAL The symbol is a local symbol. Local symbols are not
66 68 visible outside of their object file.
67 69
68 70 BIND_GLOBAL The symbol is a global symbol. Global symbols are
69 71 visible outside of their object file and may be
70 72 referred to by other ELF objects.
71 73
72 74 BIND_WEAK The symbol is a weak symbol. Weak symbols are
73 75 visible outside of their object file, but another
74 76 definition of the symbol may be used instead.
75 77
76 78 BIND_ANY This is a combination of BIND_LOCAL, BIND_GLOBAL, and
77 79 BIND_WEAK. Every symbol's binding will match this
78 80 value.
79 81
80 82 TYPE_NOTYPE The symbol's type is not specified.
81 83
82 84 TYPE_OBJECT The symbol refers to a data object. For example,
83 85 variables.
84 86
85 87 TYPE_FUNC The symbol refers to a function.
86 88
87 89 TYPE_SECTION The symbol refers to an ELF section.
88 90
89 91 TYPE_FILE The symbol refers to the name of a source file
90 92 associated with an object file.
91 93
92 94 TYPE_ANY This is a combination of TYPE_NOTYPE, TYPE_OBJECT,
93 95 TYPE_FUNC, TYPE_SECTION, and TYPE_FILE. Every
94 96 symbol's type will match this value.
95 97
96 98 To obtain all of the symbols in an object, the caller would pass the
97 99 expression BIND_ANY | TYPE_ANY in as the value of mask.
98 100
99 101 The Psymbol_iter_by_lmid() and Pxsymbol_iter() functions allow for a
100 102 link-map identifier to be specified in the lmid argument. This will
101 103 restrict the search for the object specified in object_name to the
102 104 specified link-map. There are three special link-map identifiers that
103 105 may be passed in. The symbol PR_LMID_EVERY indicates that every link-map
104 106 should be searched. The symbol LM_ID_BASE indicates that the base link-
105 107 map, the one that is used for the executable should be searched.
106 108 Finally, the symbol LM_ID_LDSO refers to the link-map that is used by the
107 109 run-time link editor, ld.so.1. The functions which do not allow a link-
108 110 map identifier to be specified always search every link-map.
109 111
110 112 By default, symbols are iterated based on the order of the symbol table
111 113 being searched. However, it is also possible to iterate based on the
112 114 name of the symbol and based on the address of the symbol. To iterate by
113 115 name use the Psymbol_iter_by_name() function. To iterate by address use
114 116 the Psymbol_iter_by_addr() function. The Psymbol_iter(),
115 117 Psymbol_iter_by_lmid(), and Pxsymbol_iter() functions all sort based on
116 118 the order of the symbol table.
117 119
118 120 The return value of the callback function func determines whether or not
119 121 iteration continues. If func returns 0, then iteration will continue.
120 122 However, if func returns non-zero, then iteration will halt and that
121 123 value will be used as the return value of the Psymbol_iter(),
122 124 Psymbol_iter_by_addr(), Psymbol_iter_by_lmid(), Psymbol_iter_by_name(),
123 125 and Pxsymbol_iter() functions. Because these functions return -1 on
124 126 internal failure, it is recommended that the callback function not return
125 127 -1 to indicate an error so that the caller may distinguish between the
126 128 failure of the callback function and the failure of these functions.
127 129
128 130 RETURN VALUES
129 131 Upon successful completion, the Psymbol_iter(), Psymbol_iter_by_addr(),
130 132 Psymbol_iter_by_lmid(), Psymbol_iter_by_name(), and Pxsymbol_iter()
131 133 functions return 0. If there was an internal error then -1 is returned.
132 134 Otherwise, if the callback function func returns non-zero, then its
133 135 return value will be returned instead.
134 136
135 137 INTERFACE STABILITY
136 138 Uncommitted
137 139
138 140 MT-LEVEL
139 141 See LOCKING in libproc(3LIB).
140 142
141 143 SEE ALSO
142 144 elf(3ELF), gelf(3ELF), libproc(3LIB), proc(4)
143 145
144 146 illumos May 11, 2016 illumos
|
↓ open down ↓ |
126 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX