1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
|
<head>
<title>mach-symbol(3) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>MACH-SYMBOL(3)</b><td align=right><b>MACH-SYMBOL(3)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
symopen, symclose, findhdr, indexsym, lookupsym, findsym, findexsym,
flookupsym, ffindsym, lookuplsym, indexlsym, findlsym, symoff,
pc2file, file2pc, line2pc, fnbound, fileline, pc2line – symbol
table access functions<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>#include <u.h><br>
#include <libc.h><br>
#include <mach.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
int symopen(Fhdr *hdr)<br>
void symclose(Fhdr *hdr)<br>
Fhdr *findhdr(char *name)<br>
extern Fhdr* fhdrlist;
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
int indexsym(uint n, Symbol *s)<br>
int lookupsym(char *fn, char *var, Symbol *s)<br>
int findsym(Loc loc, uint class, Symbol *s)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
int findexsym(Fhdr *hdr, uint n, Symbol *s)<br>
Symbol *flookupsym(Fhdr *hdr, char *name)<br>
Symbol *ffindsym(Fhdr *hdr, Loc loc, uint class)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
int indexlsym(Symbol *s1, uint n, Symbol *s2)<br>
int lookuplsym(Symbol *s1, char *name, Symbol *s2)<br>
int findlsym(Symbol *s1, Loc loc, Symbol *s2)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
int symoff(char *a, uint n, ulong addr, uint class)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
int pc2file(ulong pc, char *file, uint n, ulong *line)<br>
int pc2line(ulong pc, ulong *line)<br>
int fileline(ulong pc, char *buf, uint n)<br>
int file2pc(char *file, ulong line, ulong *pc)<br>
int line2pc(ulong basepc, ulong line, ulong *pc)<br>
int fnbound(ulong pc, ulong bounds[2])<br>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
These functions provide machine-independent access to the symbol
table of an executable file or executing process. <a href="../man3/Mach.html"><i>Mach</i>(3)</a>, <a href="../man3/mach-file.html"><i>mach-file</i>(3)</a>,
and <a href="../man3/mach-map.html"><i>mach-map</i>(3)</a> describe additional library functions for accessing
executable files and executing processes.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Symopen</i> uses the data in the <tt><font size=+1>Fhdr</font></tt> structure filled by <i>crackhdr</i>
(see <a href="../man3/mach-file.html"><i>mach-file</i>(3)</a>) to initialize in-memory structures used to
access the symbol tables contained in the file. <i>Symclose</i> frees
the structures. The rest of the functions described here access
a composite symbol table made up of all currently open tables.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The set of all currently open <tt><font size=+1>Fhdr</font></tt>s is maintained as a linked
list starting at <i>fhdrlist</i> (chained via <tt><font size=+1>Fhdr.next</font></tt>).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Findhdr</i> searches the currently open <tt><font size=+1>Fhdr</font></tt>s for one whose file name
ends with the path <i>name</i> (that is, <tt><font size=+1>libc.so</font></tt> matches <tt><font size=+1>/usr/lib/libc.so</font></tt>
but not <tt><font size=+1>mylibc.so</font></tt>).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The <tt><font size=+1>Symbol</font></tt> data structure:<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
typedef struct Symbol Symbol;<br>
struct Symbol<br>
{<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
char *name;<br>
Loc loc;<br>
Loc hiloc;<br>
char class;<br>
char type;<br>
<i>...<br>
</i>
</table>
};<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</table>
describes a symbol table entry. The <tt><font size=+1>value</font></tt> field contains the offset
of the symbol within its address space: global variables relative
to the beginning of the data segment, text beyond the start of
the text segment, and automatic variables and parameters relative
to the stack frame. The <tt><font size=+1>type</font></tt> field contains the type of
the symbol:<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>T</font></tt> text segment symbol<br>
<tt><font size=+1>t</font></tt> static text segment symbol<br>
<tt><font size=+1>D</font></tt> data segment symbol<br>
<tt><font size=+1>d</font></tt> static data segment symbol<br>
<tt><font size=+1>B</font></tt> bss segment symbol<br>
<tt><font size=+1>b</font></tt> static bss segment symbol<br>
<tt><font size=+1>a</font></tt> automatic (local) variable symbol<br>
<tt><font size=+1>p</font></tt> function parameter symbol<br>
<tt><font size=+1>U</font></tt> undefined symbol<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</table>
The <tt><font size=+1>class</font></tt> field assigns the symbol to a general class; <tt><font size=+1>CTEXT</font></tt>,
<tt><font size=+1>CDATA</font></tt>, <tt><font size=+1>CAUTO</font></tt>, and <tt><font size=+1>CPARAM</font></tt> are the most popular.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Indexsym</i> stores information for the <i>n th</i> symbol into <i>s</i>. The symbols
are ordered by increasing address.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Lookupsym</i> fills a <tt><font size=+1>Symbol</font></tt> structure with symbol table information.
Global variables and functions are represented by a single name;
local variables and parameters are uniquely specified by a function
and variable name pair. Arguments <i>fn</i> and <i>var</i> contain the name
of a function and variable, respectively. If both are
non-zero, the symbol table is searched for a parameter or automatic
variable. If only <i>var</i> is zero, the text symbol table is searched
for function <i>fn</i>. If only <i>fn</i> is zero, the global variable table
is searched for <i>var</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Findsym</i> returns the symbol table entry of type <i>class</i> stored near
<i>addr</i>. The selected symbol is a global variable or function with
address nearest to and less than or equal to <i>addr</i>. Class specification
<tt><font size=+1>CDATA</font></tt> searches only the global variable symbol table; class <tt><font size=+1>CTEXT</font></tt>
limits the search to the text symbol table. Class
specification <tt><font size=+1>CANY</font></tt> searches the text table first, then the global
table.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Findexsym</i>, <i>flookupsym</i>, and <i>ffindsym</i> are similar to <i>indexsym</i>, <i>lookupsym</i>,
and <i>findsym</i>, but operate only on the symbols from <i>hdr</i>. <i>Flookupsym</i>
and <i>ffindsym</i> return pointers to data stored in the <i>hdr</i>, which
must not be modified or freed.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Indexlsym</i>, <i>lookuplsym</i>, and <i>findlsym</i> are similar to <i>indexsym</i>, <i>lookupsym</i>,
and <i>findsym</i>, but operate on the smaller symbol table of parameters
and variables local to the function represented by symbol <i>s1</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Indexlsym</i> writes symbol information for the <i>n</i>th local symbol of
function <i>s1</i> to <i>s2</i>. Function parameters appear first in the ordering,
followed by local symbols.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Lookuplsym</i> writes symbol information for the symbol named <i>name</i>
in function <i>s1</i> to <i>s2</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Findlsym</i> searches for a symbol local to the function <i>s1</i> whose
location is exactly <i>loc</i>, writing its symbol information to <i>s2</i>.
<i>Loc</i> is almost always an indirection through a frame pointer register;
the details vary from architecture to architecture.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Symoff</i> converts a location to a symbol reference. The string containing
that reference is of the form ‘name+offset’, where ‘name’ is the
name of the nearest symbol with an address less than or equal
to the target address, and ‘offset’ is the hexadecimal offset
beyond that symbol. If ‘offset’ is zero, only the name of the
symbol is printed. If no symbol is found within 4096 bytes of
the address, the address is formatted as a hexadecimal address.
<i>Buf</i> is the address of a buffer of <i>n</i> bytes to receive the formatted
string. <i>Addr</i> is the address to be converted. <i>Type</i> is the type
code of the search space: <tt><font size=+1>CTEXT</font></tt>, <tt><font size=+1>CDATA</font></tt>, or <tt><font size=+1>CANY</font></tt>. <i>Symoff
</i>returns the length of the formatted string contained in <i>buf</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Pc2file</i> searches the symbol table to find the file and line number
corresponding to the instruction at program counter <i>pc</i>. <i>File</i> is
the address of a buffer of <i>n</i> bytes to receive the file name. <i>Line</i>
receives the line number.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Pc2line</i> is like <i>pc2file</i> but neglects to return information about
the source file.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Fileline</i> is also like <i>pc2file</i>, but returns the file and line number
in the <i>n</i>-byte text buffer <i>buf</i>, formatted as ‘file:line’.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>File2pc</i> performs the opposite mapping: it stores in <i>pc</i> a text
address associated with line <i>line</i> in file <i>file</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Line2pc</i> is similar: it converts a line number to an instruction
address, storing it in <i>pc</i>. Since a line number does not uniquely
identify an instruction (e.g., every source file has line 1),
<i>basepc</i> specifies a text address from which the search begins.
Usually this is the address of the first function in the file
of interest.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Fnbound</i> returns the start and end addresses of the function containing
the text address supplied as the first argument. The second argument
is an array of two unsigned longs; <i>fnbound</i> places the bounding
addresses of the function in the first and second elements of
this array. The start address is the address of the
first instruction of the function; the end address is the first
address beyond the end of the target function.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
All functions return 0 on success and –1 on error. When an error
occurs, a message describing it is stored in the system error
buffer where it is available via <i>errstr</i>.<br>
</table>
<p><font size=+1><b>SOURCE </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>/usr/local/plan9/src/libmach<br>
</font></tt>
</table>
<p><font size=+1><b>SEE ALSO </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<a href="../man3/mach.html"><i>mach</i>(3)</a>, <a href="../man3/mach-file.html"><i>mach-file</i>(3)</a>, <a href="../man3/mach-map.html"><i>mach-map</i>(3)</a><br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>
|