NAME

       libunwind-ptrace -- ptrace() support in libunwind

SYNOPSIS

       #include <libunwind-ptrace.h>

       unw_accessors_t _UPT_accessors;

       void *_UPT_create(pid_t);
       void _UPT_destroy(void *);

       int _UPT_find_proc_info(unw_addr_space_t, unw_word_t, unw_proc_info_t *, int, void *);
       void _UPT_put_unwind_info(unw_addr_space_t, unw_proc_info_t *, void *);
       int _UPT_get_dyn_info_list_addr(unw_addr_space_t, unw_word_t *, void *);
       int _UPT_access_mem(unw_addr_space_t, unw_word_t, unw_word_t *, int, void *);
       int _UPT_access_reg(unw_addr_space_t, unw_regnum_t, unw_word_t *, int, void *);
       int _UPT_access_fpreg(unw_addr_space_t, unw_regnum_t, unw_fpreg_t *, int, void *);
       int _UPT_get_proc_name(unw_addr_space_t, unw_word_t, char *, size_t, unw_word_t *, void *);
       int _UPT_resume(unw_addr_space_t, unw_cursor_t *, void *);

DESCRIPTION

       The ptrace(2) system-call makes it possible for a process to gain access to the machine-state and virtual
       memory of another process. With the right set of call-back routines, it is therefore possible to hook  up
       libunwind  to  another process via ptrace(2).  While it's not very difficult to do so directly, libunwind
       further facilitates this task by providing ready-to-use callbacks for  this  purpose.  The  routines  and
       variables   implementing   this   facility   use   a   name-prefix   of   _UPT,   which   is  stands  for
       ``unwind-via-ptrace''.

       An application that wants to use the _UPT-facility first needs to create a  new  libunwind  address-space
       that  represents the target process. This is done by calling unw_create_addr_space().  In many cases, the
       application will simply want to pass the address of _UPT_accessors as the first argument to this routine.
       Doing  so  will  ensure  that  libunwind will be able to properly unwind the target process.  However, in
       special circumstances, an application may prefer to use only portions of  the  _UPT-facility.   For  this
       reason,  the  individual callback routines (_UPT_find_proc_info(), _UPT_put_unwind_info(), etc.) are also
       available for direct use. Of course, the addresses of  these  routines  could  also  be  picked  up  from
       _UPT_accessors,  but  doing  so would prevent static initialization. Also, when using _UPT_accessors, all
       the callback routines will be linked into the application, even if they are never actually called.

       Next, the application can turn on ptrace-mode on the target process, either by  forking  a  new  process,
       invoking  PTRACE_TRACEME,  and then starting the target program (via execve(2)), or by directly attaching
       to an already running process (via PTRACE_ATTACH).  Either way, once the process-ID (pid) of  the  target
       process  is  known, a _UPT-info-structure can be created by calling _UPT_create(), passing the pid of the
       target process as the  only  argument.  The  returned  void-pointer  then  needs  to  be  passed  as  the
       ``argument'' pointer (third argument) to unw_init_remote().

       The  _UPT_resume()  routine  can  be  used  to  resume execution of the target process. It simply invokes
       ptrace(2) with a command value of PTRACE_CONT.

       When the application is done using libunwind on the target process, _UPT_destroy() needs  to  be  called,
       passing  it  the void-pointer that was returned by the corresponding call to _UPT_create().  This ensures
       that all memory and other resources are freed up.

AVAILABILITY

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

THREAD SAFETY

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

RETURN VALUE

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

FILES

       libunwind-ptrace.h
               Headerfile to include when using the interface defined by this library.

       -lunwind-ptrace -lunwind-generic
               Linker-switches to add when building a program that uses the functions defined by this library.

SEE ALSO

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

AUTHOR

       David Mosberger-Tang
       Email: dmosberger@gmail.com
       WWW: http://www.nongnu.org/libunwind/.