unw_set_caching_policy(3) [debian man page]

UNW_SET_CACHING_POLICY(3)				       Programming Library					 UNW_SET_CACHING_POLICY(3)

NAME

       unw_set_caching_policy -- set unwind caching policy

SYNOPSIS

       #include <libunwind.h>

       int unw_set_caching_policy(unw_addr_space_t as, unw_caching_policy_t policy);

DESCRIPTION

       The  unw_set_caching_policy()  routine  sets the caching policy of address space as to the policy specified by argument policy.	The policy
       argument can take one of three possible values:

       UNW_CACHE_NONE
	       Turns off caching completely. This also implicitly flushes the contents of all caches as if unw_flush_cache() had been called.

       UNW_CACHE_GLOBAL
	       Enables caching using a global cache that is shared by all threads. If global caching is unavailable or unsupported, libunwind  may
	      fall back on using a per-thread cache, as if UNW_CACHE_PER_THREAD had been specified.

       UNW_CACHE_PER_THREAD
	       Enables	caching  using	thread-local  caches. If a thread-local caching are unavailable or unsupported, libunwind may fall back on
	      using a global cache, as if UNW_CACHE_GLOBAL had been specified.

       If caching is enabled, an application must be prepared to make appropriate calls to unw_flush_cache() whenever the target changes in a  way
       that  could  affect  the validity of cached information.  For example, after unloading (removing) a shared library, unw_flush_cache() would
       have to be called (at least) for the address-range that was covered by the shared library.

       For  address  spaces  created  via  unw_create_addr_space(3),  caching  is  turned  off	by  default.   For   the   local   address   space
       unw_local_addr_space, caching is turned on by default.

RETURN VALUE

       On successful completion, unw_set_caching_policy() returns 0.  Otherwise the negative value of one of the error-codes below is returned.

THREAD AND SIGNAL SAFETY

       unw_set_caching_policy() is thread-safe but not safe to use from a signal handler.

ERRORS

       UNW_ENOMEM
	       The desired caching policy could not be established because the application is out of memory.

SEE ALSO

       libunwind(3), unw_create_addr_space(3), unw_flush_cache(3)

AUTHOR

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

Programming Library						  16 August 2007					 UNW_SET_CACHING_POLICY(3)

LIBUNWIND-PTRACE(3)					       Programming Library					       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 rou-
       tines (_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/.

Programming Library						  16 August 2007					       LIBUNWIND-PTRACE(3)