doc/unw_set_caching_policy.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:45 MDT 2007
   3 .\" NOTE: This file is generated, DO NOT EDIT.
   4 .de Vb
   5 .ft CW
   6 .nf
   7 ..
   8 .de Ve
   9 .ft R
  10
  11 .fi
  12 ..
  13 .TH "UNW\\_SET\\_CACHING\\_POLICY" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 unw_set_caching_policy
  16 \-\- set unwind caching policy
  17 .PP
  18 .SH SYNOPSIS
  19
  20 .PP
  21 #include <libunwind.h>
  22 .br
  23 .PP
  24 int
  25 unw_set_caching_policy(unw_addr_space_t
  26 as,
  27 unw_caching_policy_t
  28 policy);
  29 .br
  30 .PP
  31 .SH DESCRIPTION
  32
  33 .PP
  34 The unw_set_caching_policy()
  35 routine sets the caching policy
  36 of address space as
  37 to the policy specified by argument
  38 policy\&.
  39 The policy
  40 argument can take one of three
  41 possible values:
  42 .TP
  43 UNW_CACHE_NONE
  44  Turns off caching completely. This
  45 also implicitly flushes the contents of all caches as if
  46 unw_flush_cache()
  47 had been called.
  48 .TP
  49 UNW_CACHE_GLOBAL
  50  Enables caching using a global cache
  51 that is shared by all threads. If global caching is unavailable or
  52 unsupported, libunwind
  53 may fall back on using a per\-thread
  54 cache, as if UNW_CACHE_PER_THREAD
  55 had been specified.
  56 .TP
  57 UNW_CACHE_PER_THREAD
  58  Enables caching using
  59 thread\-local caches. If a thread\-local caching are unavailable or
  60 unsupported, libunwind
  61 may fall back on using a global cache,
  62 as if UNW_CACHE_GLOBAL
  63 had been specified.
  64 .PP
  65 If caching is enabled, an application must be prepared to make
  66 appropriate calls to unw_flush_cache()
  67 whenever the target
  68 changes in a way that could affect the validity of cached information.
  69 For example, after unloading (removing) a shared library,
  70 unw_flush_cache()
  71 would have to be called (at least) for the
  72 address\-range that was covered by the shared library.
  73 .PP
  74 For address spaces created via unw_create_addr_space(3),
  75 caching is turned off by default. For the local address space
  76 unw_local_addr_space,
  77 caching is turned on by default.
  78 .PP
  79 .SH RETURN VALUE
  80
  81 .PP
  82 On successful completion, unw_set_caching_policy()
  83 returns 0.
  84 Otherwise the negative value of one of the error\-codes below is
  85 returned.
  86 .PP
  87 .SH THREAD AND SIGNAL SAFETY
  88
  89 .PP
  90 unw_set_caching_policy()
  91 is thread\-safe but \fInot\fP
  92 safe
  93 to use from a signal handler.
  94 .PP
  95 .SH ERRORS
  96
  97 .PP
  98 .TP
  99 UNW_ENOMEM
 100  The desired caching policy could not be
 101 established because the application is out of memory.
 102 .PP
 103 .SH SEE ALSO
 104
 105 .PP
 106 libunwind(3),
 107 unw_create_addr_space(3),
 108 unw_flush_cache(3)
 109 .PP
 110 .SH AUTHOR
 111
 112 .PP
 113 David Mosberger\-Tang
 114 .br
 115 Email: \fBdmosberger@gmail.com\fP
 116 .br
 117 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 118 .\" NOTE: This file is generated, DO NOT EDIT.