doc/libunwind-ptrace.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
   3 .\" NOTE: This file is generated, DO NOT EDIT.
   4 .de Vb
   5 .ft CW
   6 .nf
   7 ..
   8 .de Ve
   9 .ft R
  10
  11 .fi
  12 ..
  13 .TH "LIBUNWIND\-PTRACE" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 libunwind\-ptrace
  16 \-\- ptrace() support in libunwind
  17 .PP
  18 .SH SYNOPSIS
  19
  20 .PP
  21 #include <libunwind\-ptrace.h>
  22 .br
  23 .PP
  24 unw_accessors_t
  25 _UPT_accessors;
  26 .br
  27 .PP
  28 void *_UPT_create(pid_t);
  29 .br
  30 void
  31 _UPT_destroy(void *);
  32 .br
  33 .PP
  34 int
  35 _UPT_find_proc_info(unw_addr_space_t,
  36 unw_word_t,
  37 unw_proc_info_t *,
  38 int,
  39 void *);
  40 .br
  41 void
  42 _UPT_put_unwind_info(unw_addr_space_t,
  43 unw_proc_info_t *,
  44 void *);
  45 .br
  46 int
  47 _UPT_get_dyn_info_list_addr(unw_addr_space_t,
  48 unw_word_t *,
  49 void *);
  50 .br
  51 int
  52 _UPT_access_mem(unw_addr_space_t,
  53 unw_word_t,
  54 unw_word_t *,
  55 int,
  56 void *);
  57 .br
  58 int
  59 _UPT_access_reg(unw_addr_space_t,
  60 unw_regnum_t,
  61 unw_word_t *,
  62 int,
  63 void *);
  64 .br
  65 int
  66 _UPT_access_fpreg(unw_addr_space_t,
  67 unw_regnum_t,
  68 unw_fpreg_t *,
  69 int,
  70 void *);
  71 .br
  72 int
  73 _UPT_get_proc_name(unw_addr_space_t,
  74 unw_word_t,
  75 char *,
  76 size_t,
  77 unw_word_t *,
  78 void *);
  79 .br
  80 int
  81 _UPT_resume(unw_addr_space_t,
  82 unw_cursor_t *,
  83 void *);
  84 .br
  85 .PP
  86 .SH DESCRIPTION
  87
  88 .PP
  89 The ptrace(2)
  90 system\-call makes it possible for a process to
  91 gain access to the machine\-state and virtual memory of \fIanother\fP
  92 process. With the right set of call\-back routines, it is therefore
  93 possible to hook up libunwind
  94 to another process via
  95 ptrace(2).
  96 While it\&'s not very difficult to do so directly,
  97 libunwind
  98 further facilitates this task by providing
  99 ready\-to\-use callbacks for this purpose. The routines and variables
 100 implementing this facility use a name\-prefix of _UPT,
 101 which is
 102 stands for ``unwind\-via\-ptrace\&''\&.
 103 .PP
 104 An application that wants to use the _UPT\-facility
 105 first needs
 106 to create a new libunwind
 107 address\-space that represents the
 108 target process. This is done by calling
 109 unw_create_addr_space().
 110 In many cases, the application
 111 will simply want to pass the address of _UPT_accessors
 112 as the
 113 first argument to this routine. Doing so will ensure that
 114 libunwind
 115 will be able to properly unwind the target process.
 116 However, in special circumstances, an application may prefer to use
 117 only portions of the _UPT\-facility.
 118 For this reason, the
 119 individual callback routines (_UPT_find_proc_info(),
 120 _UPT_put_unwind_info(),
 121 etc.) are also available for direct
 122 use. Of course, the addresses of these routines could also be picked
 123 up from _UPT_accessors,
 124 but doing so would prevent static
 125 initialization. Also, when using _UPT_accessors,
 126 \fIall\fP
 127 the callback routines will be linked into the application, even if
 128 they are never actually called.
 129 .PP
 130 Next, the application can turn on ptrace\-mode on the target process,
 131 either by forking a new process, invoking PTRACE_TRACEME,
 132 and
 133 then starting the target program (via execve(2)),
 134 or by
 135 directly attaching to an already running process (via
 136 PTRACE_ATTACH).
 137 Either way, once the process\-ID (pid) of the
 138 target process is known, a _UPT\-info\-structure
 139 can be created
 140 by calling _UPT_create(),
 141 passing the pid of the target process
 142 as the only argument. The returned void\-pointer then needs to be
 143 passed as the ``argument\&'' pointer (third argument) to
 144 unw_init_remote().
 145 .PP
 146 The _UPT_resume()
 147 routine can be used to resume execution of
 148 the target process. It simply invokes ptrace(2)
 149 with a command
 150 value of PTRACE_CONT\&.
 151 .PP
 152 When the application is done using libunwind
 153 on the target
 154 process, _UPT_destroy()
 155 needs to be called, passing it the
 156 void\-pointer that was returned by the corresponding call to
 157 _UPT_create().
 158 This ensures that all memory and other
 159 resources are freed up.
 160 .PP
 161 .SH AVAILABILITY
 162
 163 .PP
 164 Since ptrace(2)
 165 works within a single machine only, the
 166 _UPT\-facility
 167 by definition is not available in
 168 libunwind\-versions
 169 configured for cross\-unwinding.
 170 .PP
 171 .SH THREAD SAFETY
 172
 173 .PP
 174 The _UPT\-facility
 175 assumes that a single _UPT\-info
 176 structure is never shared between threads. Because of this, no
 177 explicit locking is used. As long as only one thread uses
 178 a _UPT\-info
 179 structure at any given time, this facility
 180 is thread\-safe.
 181 .PP
 182 .SH RETURN VALUE
 183
 184 .PP
 185 _UPT_create()
 186 may return a NULL
 187 pointer if it fails
 188 to create the _UPT\-info\-structure
 189 for any reason. For the
 190 current implementation, the only reason this call may fail is when the
 191 system is out of memory.
 192 .PP
 193 .SH FILES
 194
 195 .PP
 196 .TP
 197 libunwind\-ptrace.h
 198  Headerfile to include when using the
 199 interface defined by this library.
 200 .TP
 201 \fB\-l\fPunwind\-ptrace \fB\-l\fPunwind\-generic
 202  Linker\-switches to add when building a program that uses the
 203 functions defined by this library.
 204 .PP
 205 .SH SEE ALSO
 206
 207 .PP
 208 execve(2),
 209 libunwind(3),
 210 ptrace(2)
 211 .PP
 212 .SH AUTHOR
 213
 214 .PP
 215 David Mosberger\-Tang
 216 .br
 217 Email: \fBdmosberger@gmail.com\fP
 218 .br
 219 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 220 .\" NOTE: This file is generated, DO NOT EDIT.