doc/unw_set_caching_policy.tex

   1 \documentclass{article}
   2 \usepackage[fancyhdr,pdf]{latex2man}
   3
   4 \input{common.tex}
   5
   6 \begin{document}
   7
   8 \begin{Name}{3}{unw\_set\_caching\_policy}{David Mosberger-Tang}{Programming Library}{unw\_set\_caching\_policy}unw\_set\_caching\_policy -- set unwind caching policy
   9 \end{Name}
  10
  11 \section{Synopsis}
  12
  13 \File{\#include $<$libunwind.h$>$}\\
  14
  15 \Type{int} \Func{unw\_set\_caching\_policy}(\Type{unw\_addr\_space\_t} \Var{as}, \Type{unw\_caching\_policy\_t} \Var{policy});\\
  16
  17 \section{Description}
  18
  19 The \Func{unw\_set\_caching\_policy}() routine sets the caching policy
  20 of address space \Var{as} to the policy specified by argument
  21 \Var{policy}.  The \Var{policy} argument can take one of three
  22 possible values:
  23 \begin{description}
  24 \item[\Const{UNW\_CACHE\_NONE}] Turns off caching completely.  This
  25   also implicitly flushes the contents of all caches as if
  26   \Func{unw\_flush\_cache}() had been called.
  27 \item[\Const{UNW\_CACHE\_GLOBAL}] Enables caching using a global cache
  28   that is shared by all threads.  If global caching is unavailable or
  29   unsupported, \Prog{libunwind} may fall back on using a per-thread
  30   cache, as if \Const{UNW\_CACHE\_PER\_THREAD} had been specified.
  31 \item[\Const{UNW\_CACHE\_PER\_THREAD}] Enables caching using
  32   thread-local caches.  If a thread-local caching are unavailable or
  33   unsupported, \Prog{libunwind} may fall back on using a global cache,
  34   as if \Const{UNW\_CACHE\_GLOBAL} had been specified.
  35 \end{description}
  36
  37 If caching is enabled, an application must be prepared to make
  38 appropriate calls to \Func{unw\_flush\_cache}() whenever the target
  39 changes in a way that could affect the validity of cached information.
  40 For example, after unloading (removing) a shared library,
  41 \Func{unw\_flush\_cache}() would have to be called (at least) for the
  42 address-range that was covered by the shared library.
  43
  44 For address spaces created via \Func{unw\_create\_addr\_space}(3),
  45 caching is turned off by default.  For the local address space
  46 \Func{unw\_local\_addr\_space}, caching is turned on by default.
  47
  48 \section{Return Value}
  49
  50 On successful completion, \Func{unw\_set\_caching\_policy}() returns 0.
  51 Otherwise the negative value of one of the error-codes below is
  52 returned.
  53
  54 \section{Thread and Signal Safety}
  55
  56 \Func{unw\_set\_caching\_policy}() is thread-safe but \emph{not} safe
  57 to use from a signal handler.
  58
  59 \section{Errors}
  60
  61 \begin{Description}
  62 \item[\Const{UNW\_ENOMEM}] The desired caching policy could not be
  63   established because the application is out of memory.
  64 \end{Description}
  65
  66 \section{See Also}
  67
  68 \SeeAlso{libunwind(3)},
  69 \SeeAlso{unw\_create\_addr\_space(3)},
  70 \SeeAlso{unw\_flush\_cache(3)}
  71
  72 \section{Author}
  73
  74 \noindent
  75 David Mosberger-Tang\\
  76 Email: \Email{dmosberger@gmail.com}\\
  77 WWW: \URL{http://www.nongnu.org/libunwind/}.
  78 \LatexManEnd
  79
  80 \end{document}