272 lines
14 KiB
HTML
272 lines
14 KiB
HTML
<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>
|