mach-symbol(3) - Plan 9 from User Space

From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/mach-symbol.html | 272 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 man/man3/mach-symbol.html (limited to 'man/man3/mach-symbol.html') 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 @@ + +mach-symbol(3) - Plan 9 from User Space + + + + +

MACH-SYMBOL(3) MACH-SYMBOL(3) +

+
+

NAME
+ +
+ + symopen, symclose, findhdr, indexsym, lookupsym, findsym, findexsym, + flookupsym, ffindsym, lookuplsym, indexlsym, findlsym, symoff, + pc2file, file2pc, line2pc, fnbound, fileline, pc2line – symbol + table access functions
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> + #include <libc.h> + #include <mach.h> + + + int      symopen(Fhdr *hdr)
+ void     symclose(Fhdr *hdr)
+ Fhdr     *findhdr(char *name)
+ extern    Fhdr* fhdrlist; +
+ + int      indexsym(uint n, Symbol *s)
+ int      lookupsym(char *fn, char *var, Symbol *s)
+ int      findsym(Loc loc, uint class, Symbol *s) +
+ + int      findexsym(Fhdr *hdr, uint n, Symbol *s)
+ Symbol *flookupsym(Fhdr *hdr, char *name)
+ Symbol *ffindsym(Fhdr *hdr, Loc loc, uint class) +
+ + int      indexlsym(Symbol *s1, uint n, Symbol *s2)
+ int      lookuplsym(Symbol *s1, char *name, Symbol *s2)
+ int      findlsym(Symbol *s1, Loc loc, Symbol *s2) +
+ + int      symoff(char *a, uint n, ulong addr, uint class) +
+ + int      pc2file(ulong pc, char *file, uint n, ulong *line)
+ int      pc2line(ulong pc, ulong *line)
+ int      fileline(ulong pc, char *buf, uint n)
+ int      file2pc(char *file, ulong line, ulong *pc)
+ int      line2pc(ulong basepc, ulong line, ulong *pc)
+ int      fnbound(ulong pc, ulong bounds[2])
+ +
+

DESCRIPTION
+ +
+ + These functions provide machine-independent access to the symbol + table of an executable file or executing process. Mach(3), mach-file(3), + and mach-map(3) describe additional library functions for accessing + executable files and executing processes. +
+ + Symopen uses the data in the Fhdr structure filled by crackhdr + (see mach-file(3)) to initialize in-memory structures used to + access the symbol tables contained in the file. Symclose frees + the structures. The rest of the functions described here access + a composite symbol table made up of all currently open tables. + +
+ + The set of all currently open Fhdrs is maintained as a linked + list starting at fhdrlist (chained via Fhdr.next). +
+ + Findhdr searches the currently open Fhdrs for one whose file name + ends with the path name (that is, libc.so matches /usr/lib/libc.so + but not mylibc.so). +
+ + The Symbol data structure:
+ +
+ + typedef struct Symbol Symbol;
+ struct Symbol
+ {
+ +
+ + char    *name;
+ Loc    loc;
+ Loc    hiloc;
+ char    class;
+ char    type;
+ ...
+ +
+ };
+ +
+ + +
+ describes a symbol table entry. The value 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 type field contains the type of + the symbol:
+ +
+ + T     text segment symbol
+ t     static text segment symbol
+ D     data segment symbol
+ d     static data segment symbol
+ B     bss segment symbol
+ b     static bss segment symbol
+ a     automatic (local) variable symbol
+ p     function parameter symbol
+ U     undefined symbol
+ +
+ + +
+ The class field assigns the symbol to a general class; CTEXT, + CDATA, CAUTO, and CPARAM are the most popular. +
+ + Indexsym stores information for the n th symbol into s. The symbols + are ordered by increasing address. +
+ + Lookupsym fills a Symbol 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 fn and var 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 var is zero, the text symbol table is searched + for function fn. If only fn is zero, the global variable table + is searched for var. +
+ + Findsym returns the symbol table entry of type class stored near + addr. The selected symbol is a global variable or function with + address nearest to and less than or equal to addr. Class specification + CDATA searches only the global variable symbol table; class CTEXT + limits the search to the text symbol table. Class + specification CANY searches the text table first, then the global + table. +
+ + Findexsym, flookupsym, and ffindsym are similar to indexsym, lookupsym, + and findsym, but operate only on the symbols from hdr. Flookupsym + and ffindsym return pointers to data stored in the hdr, which + must not be modified or freed. +
+ + Indexlsym, lookuplsym, and findlsym are similar to indexsym, lookupsym, + and findsym, but operate on the smaller symbol table of parameters + and variables local to the function represented by symbol s1. + +
+ + Indexlsym writes symbol information for the nth local symbol of + function s1 to s2. Function parameters appear first in the ordering, + followed by local symbols. +
+ + Lookuplsym writes symbol information for the symbol named name + in function s1 to s2. +
+ + Findlsym searches for a symbol local to the function s1 whose + location is exactly loc, writing its symbol information to s2. + Loc is almost always an indirection through a frame pointer register; + the details vary from architecture to architecture. +
+ + Symoff 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. + Buf is the address of a buffer of n bytes to receive the formatted + string. Addr is the address to be converted. Type is the type + code of the search space: CTEXT, CDATA, or CANY. Symoff + returns the length of the formatted string contained in buf. +
+ + Pc2file searches the symbol table to find the file and line number + corresponding to the instruction at program counter pc. File is + the address of a buffer of n bytes to receive the file name. Line + receives the line number. +
+ + Pc2line is like pc2file but neglects to return information about + the source file. +
+ + Fileline is also like pc2file, but returns the file and line number + in the n-byte text buffer buf, formatted as ‘file:line’. +
+ + File2pc performs the opposite mapping: it stores in pc a text + address associated with line line in file file. +
+ + Line2pc is similar: it converts a line number to an instruction + address, storing it in pc. Since a line number does not uniquely + identify an instruction (e.g., every source file has line 1), + basepc specifies a text address from which the search begins. + Usually this is the address of the first function in the file + of interest. +
+ + Fnbound 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; fnbound 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. +
+ + 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 errstr.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach + +
+

SEE ALSO
+ +
+ + mach(3), mach-file(3), mach-map(3)
+ +
+ +

+ + +

		+
	+ + + +

+ + -- cgit v1.2.3