Lots of man pages.
This commit is contained in:
rsc
parent
08df2a433e
commit
cfa37a7b11
152 changed files with 25407 additions and 148 deletions
436
man/man3/symbol.3
Normal file
436
man/man3/symbol.3
Normal file
|
|
@ -0,0 +1,436 @@
|
|||
.TH SYMBOL 3
|
||||
.SH NAME
|
||||
syminit, getsym, symbase, pc2sp, pc2line, textseg, line2addr, lookup, findlocal,
|
||||
getauto, findsym, localsym, globalsym, textsym, file2pc, fileelem, filesym,
|
||||
fileline, fnbound \- symbol table access functions
|
||||
.SH SYNOPSIS
|
||||
.B #include <u.h>
|
||||
.br
|
||||
.B #include <libc.h>
|
||||
.br
|
||||
.B #include <bio.h>
|
||||
.br
|
||||
.B #include <mach.h>
|
||||
.PP
|
||||
.ta \w'\fLmachines 'u
|
||||
.B
|
||||
int syminit(int fd, Fhdr *fp)
|
||||
.PP
|
||||
.B
|
||||
Sym *getsym(int index)
|
||||
.PP
|
||||
.B
|
||||
Sym *symbase(long *nsyms)
|
||||
.PP
|
||||
.B
|
||||
int fileelem(Sym **fp, uchar *encname, char *buf, int n)
|
||||
.PP
|
||||
.B
|
||||
int filesym(int index, char *buf, int n)
|
||||
.PP
|
||||
.B
|
||||
long pc2sp(ulong pc)
|
||||
.PP
|
||||
.B
|
||||
long pc2line(ulong pc)
|
||||
.PP
|
||||
.B
|
||||
void textseg(ulong base, Fhdr *fp)
|
||||
.PP
|
||||
.B
|
||||
long line2addr(ulong line, ulong basepc)
|
||||
.PP
|
||||
.B
|
||||
int lookup(char *fn, char *var, Symbol *s)
|
||||
.PP
|
||||
.B
|
||||
int findlocal(Symbol *s1, char *name, Symbol *s2)
|
||||
.PP
|
||||
.B
|
||||
int getauto(Symbol *s1, int off, int class, Symbol *s2)
|
||||
.PP
|
||||
.B
|
||||
int findsym(long addr, int class, Symbol *s)
|
||||
.PP
|
||||
.B
|
||||
int localsym(Symbol *s, int index)
|
||||
.PP
|
||||
.B
|
||||
int globalsym(Symbol *s, int index)
|
||||
.PP
|
||||
.B
|
||||
int textsym(Symbol *s, int index)
|
||||
.PP
|
||||
.B
|
||||
long file2pc(char *file, ulong line)
|
||||
.PP
|
||||
.B
|
||||
int fileline(char *str, int n, ulong addr)
|
||||
.PP
|
||||
.B
|
||||
int fnbound(long addr, ulong *bounds)
|
||||
.SH DESCRIPTION
|
||||
These functions provide machine-independent access to the
|
||||
symbol table of an executable file or executing process.
|
||||
The latter is accessible by opening the device
|
||||
.B /proc/\fIpid\fP/text
|
||||
as described in
|
||||
.IR proc (3).
|
||||
.IR Mach (2)
|
||||
and
|
||||
.IR object (2)
|
||||
describe additional library functions
|
||||
for processing executable and object files.
|
||||
.PP
|
||||
.IR Syminit ,
|
||||
.IR getsym ,
|
||||
.IR symbase ,
|
||||
.IR fileelem ,
|
||||
.IR pc2sp ,
|
||||
.IR pc2line ,
|
||||
and
|
||||
.I line2addr
|
||||
process the symbol table contained in an executable file
|
||||
or the
|
||||
.B text
|
||||
image of an executing program.
|
||||
The symbol table is stored internally as an array of
|
||||
.B Sym
|
||||
data structures as defined in
|
||||
.IR a.out (6).
|
||||
.PP
|
||||
.I Syminit
|
||||
uses the data in the
|
||||
.B Fhdr
|
||||
structure filled by
|
||||
.I crackhdr
|
||||
(see
|
||||
.IR mach (2))
|
||||
to read the raw symbol tables from the open file descriptor
|
||||
.IR fd .
|
||||
It returns the count of the number of symbols
|
||||
or \-1 if an error occurs.
|
||||
.PP
|
||||
.I Getsym
|
||||
returns the address of the
|
||||
.IR i th
|
||||
.B Sym
|
||||
structure or zero if
|
||||
.I index
|
||||
is out of range.
|
||||
.PP
|
||||
.I Symbase
|
||||
returns the address of the first
|
||||
.B Sym
|
||||
structure in the symbol table. The number of
|
||||
entries in the symbol table is returned in
|
||||
.IR nsyms .
|
||||
.PP
|
||||
.I Fileelem
|
||||
converts a file name, encoded as described in
|
||||
.IR a.out (6),
|
||||
to a character string.
|
||||
.I Fp
|
||||
is the base of
|
||||
an array of pointers to file path components ordered by path index.
|
||||
.I Encname
|
||||
is the address of an array of encoded
|
||||
file path components in the form of a
|
||||
.B z
|
||||
symbol table entry.
|
||||
.I Buf
|
||||
and
|
||||
.I n
|
||||
specify the
|
||||
address of a receiving character buffer and its length.
|
||||
.I Fileelem
|
||||
returns the length of the null-terminated string
|
||||
that is at most
|
||||
.IR n \-1
|
||||
bytes long.
|
||||
.PP
|
||||
.I Filesym
|
||||
is a higher-level interface to
|
||||
.IR fileelem .
|
||||
It fills
|
||||
.I buf
|
||||
with the name of the
|
||||
.IR i th
|
||||
file and returns the length of the null-terminated string
|
||||
that is at most
|
||||
.IR n \-1
|
||||
bytes long.
|
||||
File names are retrieved in no particular order, although
|
||||
the order of retrieval does not vary from one pass to the next.
|
||||
A zero is returned when
|
||||
.I index
|
||||
is too large or too small or an error occurs during file name
|
||||
conversion.
|
||||
.PP
|
||||
.I Pc2sp
|
||||
returns an offset associated with
|
||||
a given value of the program counter. Adding this offset
|
||||
to the current value of the stack pointer gives the address
|
||||
of the current stack frame. This approach only applies
|
||||
to the 68020 architecture; other architectures
|
||||
use a fixed stack frame offset by a constant contained
|
||||
in a dummy local variable (called
|
||||
.BR .frame )
|
||||
in the symbol table.
|
||||
.PP
|
||||
.I Pc2line
|
||||
returns the line number of the statement associated
|
||||
with the instruction address
|
||||
.IR pc .
|
||||
The
|
||||
line number is the absolute line number in the
|
||||
source file as seen by the compiler after pre-processing; the
|
||||
original line number in the source file may be derived from this
|
||||
value using the history stacks contained in the symbol table.
|
||||
.PP
|
||||
.I Pc2sp
|
||||
and
|
||||
.I pc2line
|
||||
must know the start and end addresses of the text segment
|
||||
for proper operation. These values are calculated from the
|
||||
file header by function
|
||||
.IR syminit .
|
||||
If the text segment address is changed, the application
|
||||
program must invoke
|
||||
.I textseg
|
||||
to recalculate the boundaries of the segment.
|
||||
.I Base
|
||||
is the new base address of the text segment and
|
||||
.I fp
|
||||
points to the
|
||||
.I Fhdr
|
||||
data structure filled by
|
||||
.IR crackhdr .
|
||||
.PP
|
||||
.I Line2addr
|
||||
converts a line number to an instruction address. The
|
||||
first argument is the absolute line number in
|
||||
a file. Since a line number does not uniquely identify
|
||||
an instruction location (e.g., every source file has line 1),
|
||||
a second argument specifies a text address
|
||||
from which the search begins. Usually this
|
||||
is the address of the first function in the file of interest.
|
||||
.PP
|
||||
.IR Pc2sp ,
|
||||
.IR pc2line ,
|
||||
and
|
||||
.I line2addr
|
||||
return \-1 in the case of an error.
|
||||
.PP
|
||||
.IR Lookup ,
|
||||
.IR findlocal ,
|
||||
.IR getauto ,
|
||||
.IR findsym ,
|
||||
.IR localsym ,
|
||||
.IR globalsym ,
|
||||
.IR textsym ,
|
||||
.IR file2pc ,
|
||||
and
|
||||
.I fileline
|
||||
operate on data structures riding above the raw symbol table.
|
||||
These data structures occupy memory
|
||||
and impose a startup penalty but speed retrievals
|
||||
and provide higher-level access to the basic symbol
|
||||
table data.
|
||||
.I Syminit
|
||||
must be called
|
||||
prior to using these functions.
|
||||
The
|
||||
.B Symbol
|
||||
data structure:
|
||||
.IP
|
||||
.EX
|
||||
typedef struct {
|
||||
void *handle; /* private */
|
||||
struct {
|
||||
char *name;
|
||||
long value;
|
||||
char type;
|
||||
char class;
|
||||
};
|
||||
} Symbol;
|
||||
.EE
|
||||
.LP
|
||||
describes a symbol table entry.
|
||||
The
|
||||
.B 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
|
||||
.B type
|
||||
field contains the type of the symbol as defined in
|
||||
.IR a.out (6).
|
||||
The
|
||||
.B class
|
||||
field assigns the symbol to a general class;
|
||||
.BR CTEXT ,
|
||||
.BR CDATA ,
|
||||
.BR CAUTO ,
|
||||
and
|
||||
.B CPARAM
|
||||
are the most popular.
|
||||
.PP
|
||||
.I Lookup
|
||||
fills a
|
||||
.B 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
|
||||
.I fn
|
||||
and
|
||||
.I 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
|
||||
.I var
|
||||
is
|
||||
zero, the text symbol table is searched for function
|
||||
.IR fn .
|
||||
If only
|
||||
.I fn
|
||||
is zero, the global variable table
|
||||
is searched for
|
||||
.IR var .
|
||||
.PP
|
||||
.I Findlocal
|
||||
fills
|
||||
.I s2
|
||||
with the symbol table data of the automatic variable
|
||||
or parameter matching
|
||||
.IR name .
|
||||
.I S1
|
||||
is a
|
||||
.B Symbol
|
||||
data structure describing a function or a local variable;
|
||||
the latter resolves to its owning function.
|
||||
.PP
|
||||
.I Getauto
|
||||
searches the local symbols associated with function
|
||||
.I s1
|
||||
for an automatic variable or parameter located at stack
|
||||
offset
|
||||
.IR off .
|
||||
.I Class
|
||||
selects the class of
|
||||
variable:
|
||||
.B CAUTO
|
||||
or
|
||||
.BR CPARAM .
|
||||
.I S2
|
||||
is the address of a
|
||||
.B Symbol
|
||||
data structure to receive the symbol table information
|
||||
of the desired symbol.
|
||||
.PP
|
||||
.I Findsym
|
||||
returns the symbol table entry of type
|
||||
.I class
|
||||
stored near
|
||||
.IR addr .
|
||||
The selected symbol is a global variable or function
|
||||
with address nearest to and less than or equal to
|
||||
.IR addr .
|
||||
Class specification
|
||||
.B CDATA
|
||||
searches only the global variable symbol table; class
|
||||
.B CTEXT
|
||||
limits the search to the text symbol table.
|
||||
Class specification
|
||||
.B CANY
|
||||
searches the text table first, then the global table.
|
||||
.PP
|
||||
.I Localsym
|
||||
returns the
|
||||
.IR i th
|
||||
local variable in the function
|
||||
associated with
|
||||
.IR s .
|
||||
.I S
|
||||
may reference a function or a local variable; the latter
|
||||
resolves to its owning function.
|
||||
If the
|
||||
.IR i th
|
||||
local symbol exists,
|
||||
.I s
|
||||
is filled with the data describing it.
|
||||
.PP
|
||||
.I Globalsym
|
||||
loads
|
||||
.I s
|
||||
with the symbol table information of the
|
||||
.IR i th
|
||||
global variable.
|
||||
.PP
|
||||
.I Textsym
|
||||
loads
|
||||
.I s
|
||||
with the symbol table information of the
|
||||
.IR i th
|
||||
text symbol. The text symbols are ordered
|
||||
by increasing address.
|
||||
.PP
|
||||
.I File2pc
|
||||
returns a text address associated with
|
||||
.I line
|
||||
in file
|
||||
.IR file ,
|
||||
or -1 on an error.
|
||||
.PP
|
||||
.I Fileline
|
||||
converts text address
|
||||
.I addr
|
||||
to its equivalent
|
||||
line number in a source file. The result,
|
||||
a null terminated character string of
|
||||
the form
|
||||
.LR file:line ,
|
||||
is placed in buffer
|
||||
.I str
|
||||
of
|
||||
.I n
|
||||
bytes.
|
||||
.PP
|
||||
.I 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;
|
||||
.I 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 address of the start of the next function
|
||||
in memory, so it is beyond the end of the target function.
|
||||
.I Fnbound
|
||||
returns 1 if the address is within a text function, or zero
|
||||
if the address selects no function.
|
||||
.PP
|
||||
Functions
|
||||
.I file2pc
|
||||
and
|
||||
.I fileline
|
||||
may produce inaccurate results when applied to
|
||||
optimized code.
|
||||
.PP
|
||||
Unless otherwise specified, all functions return 1
|
||||
on success, or 0 on error. When an error occurs,
|
||||
a message describing it is stored in the system
|
||||
error buffer where it is available via
|
||||
.IR errstr .
|
||||
.SH SOURCE
|
||||
.B /sys/src/libmach
|
||||
.SH "SEE ALSO"
|
||||
.IR mach (2),
|
||||
.IR object (2),
|
||||
.IR errstr (2),
|
||||
.IR proc (3),
|
||||
.IR a.out (6)
|
||||
Loading…
Add table
Add a link
Reference in a new issue