diff options
| author | rsc <devnull@localhost> | 2005-01-14 03:45:44 +0000 |
|---|---|---|
| committer | rsc <devnull@localhost> | 2005-01-14 03:45:44 +0000 |
| commit | 78e51a8c6678b6e3dff3d619aa786669f531f4bc (patch) | |
| tree | 015e00fde4fc837fd31b705e18d17dc913829388 /man/man3/mach-symbol.html | |
| parent | 2634795b5f0053bc0ff08e5d7bbc0eda8efea061 (diff) | |
| download | plan9port-78e51a8c6678b6e3dff3d619aa786669f531f4bc.tar.gz plan9port-78e51a8c6678b6e3dff3d619aa786669f531f4bc.tar.bz2 plan9port-78e51a8c6678b6e3dff3d619aa786669f531f4bc.zip | |
checkpoint
Diffstat (limited to 'man/man3/mach-symbol.html')
| -rw-r--r-- | man/man3/mach-symbol.html | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/man/man3/mach-symbol.html b/man/man3/mach-symbol.html new file mode 100644 index 00000000..246d51b4 --- /dev/null +++ b/man/man3/mach-symbol.html @@ -0,0 +1,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> |