Free Knowledge Resources


Linux Manual Pages


Free Software * Books

Source Code

Free Media

Linux

libunwind-ptrace(3)


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/.



Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.



Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.

Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.



Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.

Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.



Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.

Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.


birds banner