1 \documentclass{article}
2 \usepackage[fancyhdr,pdf]{latex2man}
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
13 \File{\#include $<$libunwind.h$>$}\\
15 \Type{int} \Func{unw\_set\_caching\_policy}(\Type{unw\_addr\_space\_t} \Var{as}, \Type{unw\_caching\_policy\_t} \Var{policy});\\
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
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.
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.
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.
48 \section{Return Value}
50 On successful completion, \Func{unw\_set\_caching\_policy}() returns 0.
51 Otherwise the negative value of one of the error-codes below is
54 \section{Thread and Signal Safety}
56 \Func{unw\_set\_caching\_policy}() is thread-safe but \emph{not} safe
57 to use from a signal handler.
62 \item[\Const{UNW\_ENOMEM}] The desired caching policy could not be
63 established because the application is out of memory.
68 \SeeAlso{libunwind(3)},
69 \SeeAlso{unw\_create\_addr\_space(3)},
70 \SeeAlso{unw\_flush\_cache(3)}
75 David Mosberger-Tang\\
76 Email: \Email{dmosberger@gmail.com}\\
77 WWW: \URL{http://www.nongnu.org/libunwind/}.