10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
377 lines
7.6 KiB
Groff
377 lines
7.6 KiB
Groff
.TH MACH-SYMBOL 3
|
|
.SH NAME
|
|
symopen, symclose, findhdr, indexsym, lookupsym, findsym,
|
|
findexsym, flookupsym, ffindsym,
|
|
lookuplsym, indexlsym, findlsym,
|
|
symoff, pc2file, file2pc, line2pc, fnbound, fileline,
|
|
pc2line \- symbol table access functions
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.br
|
|
.B #include <mach.h>
|
|
.PP
|
|
.ta \w'\fBxxxxxxxx'u +\w'\fBxxxxxx'u
|
|
.ft B
|
|
int symopen(Fhdr *hdr)
|
|
.br
|
|
void symclose(Fhdr *hdr)
|
|
.br
|
|
Fhdr *findhdr(char *name)
|
|
.br
|
|
extern Fhdr* fhdrlist;
|
|
.PP
|
|
.ft B
|
|
int indexsym(uint n, Symbol *s)
|
|
.br
|
|
int lookupsym(char *fn, char *var, Symbol *s)
|
|
.br
|
|
int findsym(Loc loc, uint class, Symbol *s)
|
|
.PP
|
|
.ft B
|
|
int findexsym(Fhdr *hdr, uint n, Symbol *s)
|
|
.br
|
|
Symbol *flookupsym(Fhdr *hdr, char *name)
|
|
.br
|
|
Symbol *ffindsym(Fhdr *hdr, Loc loc, uint class)
|
|
.PP
|
|
.ft B
|
|
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)
|
|
.PP
|
|
.ft B
|
|
int symoff(char *a, uint n, ulong addr, uint class)
|
|
.PP
|
|
.ft B
|
|
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])
|
|
.SH DESCRIPTION
|
|
These functions provide machine-independent access to the
|
|
symbol table of an executable file or executing process.
|
|
.MR Mach 3 ,
|
|
.MR mach-file 3 ,
|
|
and
|
|
.MR mach-map 3
|
|
describe additional library functions for
|
|
accessing executable files and executing processes.
|
|
.PP
|
|
.IR Symopen
|
|
uses the data in the
|
|
.B Fhdr
|
|
structure filled by
|
|
.I crackhdr
|
|
(see
|
|
.MR mach-file 3 )
|
|
to initialize in-memory structures used to access the symbol
|
|
tables contained in the file.
|
|
.IR Symclose
|
|
frees the structures.
|
|
The rest of the functions described here access a composite
|
|
symbol table made up of all currently open tables.
|
|
.PP
|
|
The set of all currently open
|
|
.BR Fhdr s
|
|
is maintained as a linked list starting at
|
|
.I fhdrlist
|
|
(chained via
|
|
.BR Fhdr.next ).
|
|
.PP
|
|
.I Findhdr
|
|
searches the currently open
|
|
.BR Fhdr s
|
|
for one whose file name ends with the path
|
|
.I name
|
|
(that is,
|
|
.B libc.so
|
|
matches
|
|
.B /usr/lib/libc.so
|
|
but not
|
|
.BR mylibc.so ).
|
|
.PP
|
|
The
|
|
.B Symbol
|
|
data structure:
|
|
.IP
|
|
.RS
|
|
.ft B
|
|
.nf
|
|
typedef struct Symbol Symbol;
|
|
struct Symbol
|
|
{
|
|
char *name;
|
|
Loc loc;
|
|
Loc hiloc;
|
|
char class;
|
|
char type;
|
|
\fI...\fP
|
|
};
|
|
.fi
|
|
.RE
|
|
.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:
|
|
.RS
|
|
.TP
|
|
.B T
|
|
text segment symbol
|
|
.TP
|
|
.B t
|
|
static text segment symbol
|
|
.TP
|
|
.B D
|
|
data segment symbol
|
|
.TP
|
|
.B d
|
|
static data segment symbol
|
|
.TP
|
|
.B B
|
|
bss segment symbol
|
|
.TP
|
|
.B b
|
|
static bss segment symbol
|
|
.TP
|
|
.B a
|
|
automatic (local) variable symbol
|
|
.TP
|
|
.B p
|
|
function parameter symbol
|
|
.TP
|
|
.B U
|
|
undefined symbol
|
|
.RE
|
|
.PD
|
|
.LP
|
|
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 Indexsym
|
|
stores information for the
|
|
.I n th
|
|
symbol into
|
|
.IR s .
|
|
The symbols are ordered by increasing address.
|
|
.PP
|
|
.I Lookupsym
|
|
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 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
|
|
.IR Findexsym ,
|
|
.IR flookupsym ,
|
|
and
|
|
.I ffindsym
|
|
are similar to
|
|
.IR indexsym ,
|
|
.IR lookupsym ,
|
|
and
|
|
.IR findsym ,
|
|
but operate only on the symbols from
|
|
.IR hdr .
|
|
.I Flookupsym
|
|
and
|
|
.I ffindsym
|
|
return pointers to data stored in the
|
|
.IR hdr ,
|
|
which must not be modified or freed.
|
|
.PP
|
|
.IR Indexlsym ,
|
|
.IR lookuplsym ,
|
|
and
|
|
.I findlsym
|
|
are similar to
|
|
.IR indexsym ,
|
|
.IR lookupsym ,
|
|
and
|
|
.IR findsym ,
|
|
but operate on the smaller symbol table of parameters and
|
|
variables local to the function represented by symbol
|
|
.IR s1 .
|
|
.PP
|
|
.I Indexlsym
|
|
writes symbol information for the
|
|
.IR n th
|
|
local symbol of function
|
|
.I s1
|
|
to
|
|
.IR s2 .
|
|
Function parameters appear first in the ordering, followed by local symbols.
|
|
.PP
|
|
.I Lookuplsym
|
|
writes symbol information for the symbol named
|
|
.I name
|
|
in function
|
|
.I s1
|
|
to
|
|
.IR s2 .
|
|
.PP
|
|
.I Findlsym
|
|
searches for a symbol local to the function
|
|
.I s1
|
|
whose location is exactly
|
|
.IR loc ,
|
|
writing its symbol information to
|
|
.IR s2 .
|
|
.I Loc
|
|
is almost always an indirection through a frame pointer register;
|
|
the details vary from architecture to architecture.
|
|
.PP
|
|
.I 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.
|
|
.I Buf
|
|
is the address of a buffer of
|
|
.I n
|
|
bytes to receive the formatted string.
|
|
.I Addr
|
|
is the address to be converted.
|
|
.I Type
|
|
is the type code of the search space:
|
|
.BR CTEXT ,
|
|
.BR CDATA ,
|
|
or
|
|
.BR CANY .
|
|
.I Symoff
|
|
returns the length of the formatted string contained in
|
|
.IR buf .
|
|
.PP
|
|
.I Pc2file
|
|
searches the symbol table to find the file and line number
|
|
corresponding to the instruction at program counter
|
|
.IR pc .
|
|
.I File
|
|
is the address of a buffer of
|
|
.I n
|
|
bytes to receive the file name.
|
|
.I Line
|
|
receives the line number.
|
|
.PP
|
|
.I Pc2line
|
|
is like
|
|
.I pc2file
|
|
but neglects to return information about the source file.
|
|
.PP
|
|
.I Fileline
|
|
is also like
|
|
.IR pc2file ,
|
|
but returns the file and line number in the
|
|
.IR n -byte
|
|
text buffer
|
|
.IR buf ,
|
|
formatted as
|
|
`file:line'.
|
|
.PP
|
|
.I File2pc
|
|
performs the opposite mapping:
|
|
it stores in
|
|
.I pc
|
|
a text address associated with
|
|
line
|
|
.I line
|
|
in file
|
|
.IR file .
|
|
.PP
|
|
.I Line2pc
|
|
is similar: it converts a line number to an
|
|
instruction address, storing it in
|
|
.IR pc .
|
|
Since a line number does not uniquely identify an
|
|
instruction (e.g., every source file has line 1),
|
|
.I basepc
|
|
specifies a text address from which
|
|
the search begins.
|
|
Usually this is the address of the first function in the
|
|
file of interest.
|
|
.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 first address beyond the end of the target function.
|
|
.PP
|
|
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
|
|
.IR errstr .
|
|
.SH SOURCE
|
|
.B \*9/src/libmach
|
|
.SH "SEE ALSO"
|
|
.MR mach 3 ,
|
|
.MR mach-file 3 ,
|
|
.MR mach-map 3
|