Added stackwalk/doc LaTeX files.
[dyninst.git] / stackwalk / doc / API / ProcessState.tex
1 \subsubsection{Class ProcessState}
2 \label{subsec:processstate}
3 \definedin{procstate.h}
4
5 The ProcessState class is a virtual class that defines an interface through
6 which StackwalkerAPI can access the target process. It allows access to
7 registers and memory, and provides basic information about the threads in the
8 target process. StackwalkerAPI provides two default types of \code{ProcessState}
9 objects: \code{ProcSelf} does a first party stackwalk, and \code{ProcDebug} does a third party
10 stackwalk.
11
12 A new \code{ProcessState} class can be created by inheriting from this class and
13 implementing the following functions.
14
15 \begin{apient}
16 virtual bool getRegValue(Dyninst::MachRegister reg, 
17                          Dyninst::THR_ID thread, 
18                          Dyninst::MachRegisterVal &val) = 0
19 \end{apient}
20 \apidesc{
21     This method takes a register name as input, \code{reg}, and returns the
22     value in that register in \code{val} in the thread thread.
23         
24     This method returns \code{true} on success and \code{false} on error.  
25 }
26
27 \begin{apient}
28 virtual bool readMem(void *dest, Address source, size_t size) = 0
29 \end{apient}
30 \apidesc{
31     This method reads memory from the target process. Parameter \code{dest} should
32     point to an allocated buffer of memory at least \code{size} bytes in the host
33     process. Parameter \code{source} should contain an address in the target process to
34     be read from. If this method succeeds, \code{size} bytes of memory is copied from
35     \code{source}, stored in \code{dest}, and \code{true} is returned. This
36     method returns \code{false}
37     otherwise.
38 }
39
40 \begin{apient}
41 virtual bool getThreadIds(std::vector<Dyninst::THR_ID> &threads) = 0
42 \end{apient}
43 \apidesc{
44     This method returns a list of threads whose call stacks can be walked in the
45     target process. Thread are returned in the \code{threads} vector. In some cases,
46     such as with the default \code{ProcDebug}, this method returns all of the threads
47     in the target process. In other cases, such as with \code{ProcSelf}, this method
48     returns only the calling thread. 
49
50     The first thread in the \code{threads} vector (index 0) will be used as the default
51     thread if the user requests a stackwalk without specifying an thread (see
52     \code{Walker::WalkStack}).
53     
54     This method returns \code{true} on success and \code{false} on error.  }
55
56 \begin{apient}
57 virtual bool getDefaultThread(Dyninst::THR_ID &default_tid) = 0
58 \end{apient}
59 \apidesc{
60         This method returns the thread representing the initial process in the
61     \code{default\_tid} output parameter.
62     
63     This method returns \code{true} on success and \code{false} on error.  
64 }
65
66 \begin{apient}
67 virtual Dyninst::PID getProcessID() = 0
68 \end{apient}
69 \apidesc{
70     This method returns a process ID for the target process. The default
71     \code{ProcessState} implementations (\code{ProcDebug} and \code{ProcSelf}) will return a PID on
72     UNIX systems and a HANDLE object on Windows.
73 }
74     
75 \paragraph{Class LibraryState}
76
77 \definedin{procstate.h}
78
79 \code{LibraryState} is a helper class for \code{ProcessState} that provides information about
80 the current DSOs (libraries and executables) that are loaded into a process'
81 address space. FrameSteppers frequently use the LibraryState to get the DSO
82 through which they are attempting to stack walk.
83
84 Each \code{Library} is represented using a \code{LibAddrPair} object, which is defined as
85 follows:
86
87 \begin{apient}
88 typedef std::pair<std::string, Dyninst::Address> LibAddrPair
89 \end{apient}
90 \apidesc{
91     \code{LibAddrPair.first} refers to the file path of the library that was
92     loaded, and \code{LibAddrPair.second} is the load address of that library in
93     the process' address space. The load address of a library can be added to a
94     symbol offset from the file in order to get the absolute address of a
95     symbol.
96 }
97
98 \begin{apient}
99 virtual bool getLibraryAtAddr(Address addr, LibAddrPair &lib) = 0
100 \end{apient}
101 \apidesc{
102     This method returns a DSO, using the \code{lib} output parameter, that is
103     loaded over address \code{addr} in the current process.
104
105     This method returns \code{false} if no library is loaded over \code{addr} or
106     an error occurs, and \code{true} if it successfully found a library.
107 }
108
109 \begin{apient}
110 virtual bool getLibraries(std::vector<LibAddrPair> &libs) = 0
111 \end{apient}
112 \apidesc{
113         This method returns all DSOs that are loaded into the process' address space
114     in the output vector parameter, \code{libs}. 
115     
116     This method returns \code{true} on success and \code{false} on error.  
117 }
118
119 \begin{apient}
120 virtual void notifyOfUpdate() = 0
121 \end{apient}
122 \apidesc{
123     This method is called by the \code{ProcessState} when it detects a change in
124     the process' list of loaded libraries. Implementations of
125     \code{LibraryStates} should use this method to refresh their lists of loaded libraries.
126 }
127
128 \begin{apient}
129 virtual Address getLibTrapAddress() = 0
130 \end{apient}
131 \apidesc{
132     Some platforms that implement the System/V standard (Linux, Solaris,
133     BlueGene/P) use a trap event to determine when a process loads a library. A
134     trap instruction is inserted into a certain address, and that trap will
135     execute whenever the list of loaded libraries change. 
136         
137     On System/V platforms this method should return the address where a trap
138     should be inserted to watch for libraries loading and unloading. The
139     ProcessState object will insert a trap at this address and then call
140     notifyOfUpdate when that trap triggers.
141         
142     On non-System/V platforms this method should return 0.  
143 }