Ubuntu Manpage: libunwind-nto -- QNX Neutrino support in libunwind

Provided by: libunwind-dev_1.8.1-0.1ubuntu1_amd64

NAME

       libunwind-nto -- QNX Neutrino support in libunwind

SYNOPSIS

       #include <libunwind-nto.h>

       unw_accessors_t unw_nto_accessors;

       void *unw_nto_create(pid_t, pthread_t);
       void unw_nto_destroy(void *);

       int unw_nto_find_proc_info(unw_addr_space_t, unw_word_t, unw_proc_info_t *, int, void *);
       void unw_nto_put_unwind_info(unw_addr_space_t, unw_proc_info_t *, void *);
       int unw_nto_get_dyn_info_list_addr(unw_addr_space_t, unw_word_t *, void *);
       int unw_nto_access_mem(unw_addr_space_t, unw_word_t, unw_word_t *, int, void *);
       int unw_nto_access_reg(unw_addr_space_t, unw_regnum_t, unw_word_t *, int, void *);
       int unw_nto_access_fpreg(unw_addr_space_t, unw_regnum_t, unw_fpreg_t *, int, void *);
       int unw_nto_get_proc_name(unw_addr_space_t, unw_word_t, char *, size_t, unw_word_t *, void *);
       int unw_nto_resume(unw_addr_space_t, unw_cursor_t *, void *);

DESCRIPTION

The QNX operating system makes it possible for a process to gain access to the machine state and virtual
memory of another process, or a different thread within the same process. gain access to the machine
state and virtual memory of another it is possible to hook up libunwind to another process. 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
unw_nto, which is stands for ``unwind-via-nto''.

An application that wants to use the libunwind NTO remote needs to take the following steps.

1. Create a new libunwind address-space that represents the target process and thread. This is done
by calling unw_create_addr_space(). In many cases, the application will simply want to pass the
address of unw_nto_accessors as the first argument to this routine. Doing so will ensure that
libunwind will be able to properly unwind the target process.

2. Create an NTO info structure by calling unw_nto_create(), passing the pid and tid of the target
process thread as the arguments. This will stop the target thread. The process ID (pid) of the
target process must be known, and only a single thread can be unwound at a time so the thread ID
(tid) must also be specified.

3. The opaque pointer returned then needs to be passed as the ``argument'' pointer (third argument)
to unw_init_remote().

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

The unw_nto_resume() is not supported on the NTO remote.

In special circumstances, an application may prefer to use only portions of the libunwind NTO remote. For
this reason, the individual callback routines (unw_nto_find_proc_info(), unw_nto_put_unwind_info(), etc.)
are also available for direct use. Of course, the addresses of these routines could also be picked up
from unw_nto_accessors, but doing so would prevent static initialization. Also, when using
unw_nto_accessors, all the callback routines will be linked into the application, even if they are never
actually called.

THREAD SAFETY

       The  libunwind NTO remote assumes that a single unw_nto-info structure is never shared between threads of
       the unwinding program.  Because of this, no explicit locking is used.  As long as only one thread uses an
       NTO info structure at any given time, this facility is thread-safe.

RETURN VALUE

       unw_nto_create() may return a NULL if it fails to create the NTO info structure for any reason.

FILES

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

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

EXAMPLE

           #include <libunwind-nto.h>
           #include <stdio.h>
           #include <stdlib.h>

           int
           main (int argc, char **argv)
           {
             if (argc != 2) {
               fprintf (stderr, "usage: %s PID\n", argv[0]);
               exit (EXIT_FAILURE);
             }

             char *endptr;
             pid_t target_pid = strtoul (argv[1], &endptr, 10);
             if (target_pid == 0 && argv[1] == endptr) {
               fprintf (stderr, "usage: %s PID\n", argv[0]);
               exit (EXIT_FAILURE);
             }

             unw_addr_space_t as = unw_create_addr_space (&unw_nto_accessors, 0);
             if (!as) {
               fprintf (stderr, "unw_create_addr_space() failed");
               exit (EXIT_FAILURE);
             }

             void *ui = unw_nto_create (target_pid, (thread_t)1);
             if (!ui) {
               fprintf (stderr, "unw_nto_create() failed");
               exit (EXIT_FAILURE);
             }

             unw_cursor_t cursor;
             int ret = unw_init_remote (&cursor, as, ui);
             if (ret < 0) {
               fprintf (stderr, "unw_init_remote() failed: ret=%d\n", ret);
               exit (EXIT_FAILURE);
             }

             do {
               unw_proc_info_t pi;
               ret = unw_get_proc_info (&cursor, &pi);
               if (ret == -UNW_ENOINFO) {
                 fprintf (stdout, "no info\n");
               } else if (ret >= 0) {
                 printf ("\tproc=%#016lx-%#016lx\thandler=%#016lx lsda=%#016lx",
                         (long) pi.start_ip, (long) pi.end_ip,
                         (long) pi.handler, (long) pi.lsda);
               }
               ret = unw_step (&cursor);
             } while (ret > 0);
             if (ret < 0) {
               fprintf (stderr, "unwind failed with ret=%d\n", ret);
               exit (EXIT_FAILURE);
             }

             unw_nto_destroy (ui);
             unw_destroy_addr_space (as);
             exit (EXIT_SUCCESS);
           }