| <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> |
