xref: /external/libunwind/doc/unw_set_caching_policy.tex

\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}

\input{common.tex}

\begin{document}

\begin{Name}{3}{unw\_set\_caching\_policy}{David Mosberger-Tang}{Programming Library}{unw\_set\_caching\_policy}unw\_set\_caching\_policy -- set unwind caching policy
\end{Name}

\section{Synopsis}

\File{\#include $<$libunwind.h$>$}\\

\Type{int} \Func{unw\_set\_caching\_policy}(\Type{unw\_addr\_space\_t} \Var{as}, \Type{unw\_caching\_policy\_t} \Var{policy});\\

\section{Description}

The \Func{unw\_set\_caching\_policy}() routine sets the caching policy
of address space \Var{as} to the policy specified by argument
\Var{policy}.  The \Var{policy} argument can take one of three
possible values:
\begin{description}
\item[\Const{UNW\_CACHE\_NONE}] Turns off caching completely.  This
  also implicitly flushes the contents of all caches as if
  \Func{unw\_flush\_cache}() had been called.
\item[\Const{UNW\_CACHE\_GLOBAL}] Enables caching using a global cache
  that is shared by all threads.  If global caching is unavailable or
  unsupported, \Prog{libunwind} may fall back on using a per-thread
  cache, as if \Const{UNW\_CACHE\_PER\_THREAD} had been specified.
\item[\Const{UNW\_CACHE\_PER\_THREAD}] Enables caching using
  thread-local caches.  If a thread-local caching are unavailable or
  unsupported, \Prog{libunwind} may fall back on using a global cache,
  as if \Const{UNW\_CACHE\_GLOBAL} had been specified.
\end{description}

If caching is enabled, an application must be prepared to make
appropriate calls to \Func{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,
\Func{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 \Func{unw\_create\_addr\_space}(3),
caching is turned off by default.  For the local address space
\Func{unw\_local\_addr\_space}, caching is turned on by default.

\section{Return Value}

On successful completion, \Func{unw\_set\_caching\_policy}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.

\section{Thread and Signal Safety}

\Func{unw\_set\_caching\_policy}() is thread-safe but \emph{not} safe
to use from a signal handler.

\section{Errors}

\begin{Description}
\item[\Const{UNW\_ENOMEM}] The desired caching policy could not be
  established because the application is out of memory.
\end{Description}

\section{See Also}

\SeeAlso{libunwind(3)},
\SeeAlso{unw\_create\_addr\_space(3)},
\SeeAlso{unw\_flush\_cache(3)}

\section{Author}

\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd

\end{document}