Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MACH-SYMBOL(3)		   Library Functions Manual		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  exe-
       cutable 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  ta-
       ble 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  seg-
       ment,  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 vari-
       able  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 near-
       est  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 func-
       tion s1 to s2.  Function	parameters appear first	in the ordering,  fol-
       lowed by	local symbols.

       Lookuplsym writes symbol	information for	the symbol named name in func-
       tion 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 contain-
       ing 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 sym-
       bol.   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 cor-
       responding to the instruction at	program	counter	pc.  File is  the  ad-
       dress  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 ad-
       dress, storing it in pc.	 Since a line number does not  uniquely	 iden-
       tify an instruction (e.g., every	source file has	line 1), basepc	speci-
       fies 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 ad-
       dresses of the function in the first and	second elements	of this	array.
       The  start address is the address of the	first instruction of the func-
       tion; 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 oc-
       curs, 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)

								MACH-SYMBOL(3)

NAME | SYNOPSIS | DESCRIPTION | SOURCE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mach-symbol&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help