unw_set_caching_policy.tex revision 972aec70ba48f64db9b635a47a497cd65489d343 
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
19The \Func{unw\_set\_caching\_policy}() routine sets the caching policy
20of address space \Var{as} to the policy specified by argument
21\Var{policy}.  The \Var{policy} argument can take one of three
22possible 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
37If caching is enabled, an application must be prepared to make
38appropriate calls to \Func{unw\_flush\_cache}() whenever the target
39changes in a way that could affect the validity of cached information.
40For example, after unloading (removing) a shared library,
41\Func{unw\_flush\_cache}() would have to be called (at least) for the
42address-range that was covered by the shared library.
43
44For address spaces created via \Func{unw\_create\_addr\_space}(3),
45caching 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
50On successful completion, \Func{unw\_set\_caching\_policy}() returns 0.
51Otherwise the negative value of one of the error-codes below is
52returned.
53
54\section{Thread and Signal Safety}
55
56\Func{unw\_set\_caching\_policy}() is thread-safe but \emph{not} safe
57to 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
75David Mosberger-Tang\\
76Hewlett-Packard Labs\\
77Palo-Alto, CA 94304\\
78Email: \Email{davidm@hpl.hp.com}\\
79WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
80\LatexManEnd
81
82\end{document}
83