1LIBUNWIND-PTRACE(3)          Programming Library           LIBUNWIND-PTRACE(3)
2
3
4

NAME

6       libunwind-ptrace -- ptrace() support in libunwind
7

SYNOPSIS

9       #include <libunwind-ptrace.h>
10
11       unw_accessors_t _UPT_accessors;
12
13       void *_UPT_create(pid_t);
14       void _UPT_destroy(void *);
15
16       int  _UPT_find_proc_info(unw_addr_space_t,  unw_word_t, unw_proc_info_t
17       *, int, void *);
18       void _UPT_put_unwind_info(unw_addr_space_t, unw_proc_info_t *, void *);
19       int _UPT_get_dyn_info_list_addr(unw_addr_space_t,  unw_word_t  *,  void
20       *);
21       int  _UPT_access_mem(unw_addr_space_t,  unw_word_t,  unw_word_t *, int,
22       void *);
23       int _UPT_access_reg(unw_addr_space_t, unw_regnum_t, unw_word_t *,  int,
24       void *);
25       int  _UPT_access_fpreg(unw_addr_space_t,  unw_regnum_t,  unw_fpreg_t *,
26       int, void *);
27       int _UPT_get_proc_name(unw_addr_space_t, unw_word_t,  char  *,  size_t,
28       unw_word_t *, void *);
29       int _UPT_resume(unw_addr_space_t, unw_cursor_t *, void *);
30

DESCRIPTION

32       The  ptrace(2)  system-call  makes  it  possible  for a process to gain
33       access to the machine-state and virtual memory of another process. With
34       the  right  set of call-back routines, it is therefore possible to hook
35       up libunwind to another process via ptrace(2).   While  it's  not  very
36       difficult to do so directly, libunwind further facilitates this task by
37       providing ready-to-use callbacks for this  purpose.  The  routines  and
38       variables  implementing  this facility use a name-prefix of _UPT, which
39       is stands for ``unwind-via-ptrace''.
40
41       An application that wants to use the _UPT-facility first needs to  cre‐
42       ate  a  new libunwind address-space that represents the target process.
43       This is done by calling unw_create_addr_space().  In  many  cases,  the
44       application  will  simply want to pass the address of _UPT_accessors as
45       the first argument to this routine. Doing so will ensure that libunwind
46       will  be  able to properly unwind the target process.  However, in spe‐
47       cial circumstances, an application may prefer to use only  portions  of
48       the  _UPT-facility.   For this reason, the individual callback routines
49       (_UPT_find_proc_info(), _UPT_put_unwind_info(), etc.) are  also  avail‐
50       able  for  direct use. Of course, the addresses of these routines could
51       also be picked up from  _UPT_accessors,  but  doing  so  would  prevent
52       static  initialization.  Also, when using _UPT_accessors, all the call‐
53       back routines will be linked into the application,  even  if  they  are
54       never actually called.
55
56       Next,  the  application  can turn on ptrace-mode on the target process,
57       either by forking a new  process,  invoking  PTRACE_TRACEME,  and  then
58       starting  the  target program (via execve(2)), or by directly attaching
59       to an already running process (via PTRACE_ATTACH).   Either  way,  once
60       the process-ID (pid) of the target process is known, a _UPT-info-struc‐
61       ture can be created by calling _UPT_create(), passing the  pid  of  the
62       target  process  as  the  only argument. The returned void-pointer then
63       needs to be passed as the  ``argument''  pointer  (third  argument)  to
64       unw_init_remote().
65
66       The _UPT_resume() routine can be used to resume execution of the target
67       process.  It  simply  invokes  ptrace(2)  with  a  command   value   of
68       PTRACE_CONT.
69
70       When  the  application  is  done using libunwind on the target process,
71       _UPT_destroy() needs to be called, passing it the void-pointer that was
72       returned by the corresponding call to _UPT_create().  This ensures that
73       all memory and other resources are freed up.
74

AVAILABILITY

76       Since ptrace(2) works within a single machine only,  the  _UPT-facility
77       by  definition  is  not  available in libunwind-versions configured for
78       cross-unwinding.
79

THREAD SAFETY

81       The _UPT-facility assumes that a single _UPT-info  structure  is  never
82       shared  between  threads. Because of this, no explicit locking is used.
83       As long as only one thread uses a  _UPT-info  structure  at  any  given
84       time, this facility is thread-safe.
85

RETURN VALUE

87       _UPT_create()  may  return  a  NULL  pointer  if it fails to create the
88       _UPT-info-structure for any reason. For the current implementation, the
89       only reason this call may fail is when the system is out of memory.
90

FILES

92       libunwind-ptrace.h
93               Headerfile  to include when using the interface defined by this
94              library.
95
96       -lunwind-ptrace -lunwind-generic
97               Linker-switches to add when building a program  that  uses  the
98              functions defined by this library.
99

SEE ALSO

101       execve(2), libunwind(3), ptrace(2)
102

AUTHOR

104       David Mosberger-Tang
105       Hewlett-Packard Labs
106       Palo-Alto, CA 94304
107       Email: davidm@hpl.hp.com
108       WWW: http://www.hpl.hp.com/research/linux/libunwind/.
109
110
111
112Programming Library             05 August 2004             LIBUNWIND-PTRACE(3)
Impressum