diff options
Diffstat (limited to 'src/pal/src/libunwind/doc/libunwind-ptrace.man')
| -rw-r--r-- | src/pal/src/libunwind/doc/libunwind-ptrace.man | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/src/pal/src/libunwind/doc/libunwind-ptrace.man b/src/pal/src/libunwind/doc/libunwind-ptrace.man new file mode 100644 index 0000000000..985fcae275 --- /dev/null +++ b/src/pal/src/libunwind/doc/libunwind-ptrace.man @@ -0,0 +1,220 @@ +'\" t +.\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007 +.\" NOTE: This file is generated, DO NOT EDIT. +.de Vb +.ft CW +.nf +.. +.de Ve +.ft R + +.fi +.. +.TH "LIBUNWIND\-PTRACE" "3" "16 August 2007" "Programming Library " "Programming Library " +.SH NAME +libunwind\-ptrace +\-\- ptrace() support in libunwind +.PP +.SH SYNOPSIS + +.PP +#include <libunwind\-ptrace.h> +.br +.PP +unw_accessors_t +_UPT_accessors; +.br +.PP +void *_UPT_create(pid_t); +.br +void +_UPT_destroy(void *); +.br +.PP +int +_UPT_find_proc_info(unw_addr_space_t, +unw_word_t, +unw_proc_info_t *, +int, +void *); +.br +void +_UPT_put_unwind_info(unw_addr_space_t, +unw_proc_info_t *, +void *); +.br +int +_UPT_get_dyn_info_list_addr(unw_addr_space_t, +unw_word_t *, +void *); +.br +int +_UPT_access_mem(unw_addr_space_t, +unw_word_t, +unw_word_t *, +int, +void *); +.br +int +_UPT_access_reg(unw_addr_space_t, +unw_regnum_t, +unw_word_t *, +int, +void *); +.br +int +_UPT_access_fpreg(unw_addr_space_t, +unw_regnum_t, +unw_fpreg_t *, +int, +void *); +.br +int +_UPT_get_proc_name(unw_addr_space_t, +unw_word_t, +char *, +size_t, +unw_word_t *, +void *); +.br +int +_UPT_resume(unw_addr_space_t, +unw_cursor_t *, +void *); +.br +.PP +.SH DESCRIPTION + +.PP +The ptrace(2) +system\-call makes it possible for a process to +gain access to the machine\-state and virtual memory of \fIanother\fP +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\&''\&. +.PP +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, +\fIall\fP +the callback routines will be linked into the application, even if +they are never actually called. +.PP +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(). +.PP +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\&. +.PP +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. +.PP +.SH AVAILABILITY + +.PP +Since ptrace(2) +works within a single machine only, the +_UPT\-facility +by definition is not available in +libunwind\-versions +configured for cross\-unwinding. +.PP +.SH THREAD SAFETY + +.PP +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. +.PP +.SH RETURN VALUE + +.PP +_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. +.PP +.SH FILES + +.PP +.TP +libunwind\-ptrace.h + Headerfile to include when using the +interface defined by this library. +.TP +\fB\-l\fPunwind\-ptrace \fB\-l\fPunwind\-generic + Linker\-switches to add when building a program that uses the +functions defined by this library. +.PP +.SH SEE ALSO + +.PP +execve(2), +libunwind(3), +ptrace(2) +.PP +.SH AUTHOR + +.PP +David Mosberger\-Tang +.br +Email: \fBdmosberger@gmail.com\fP +.br +WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&. +.\" NOTE: This file is generated, DO NOT EDIT. |