Home | History | Annotate | Download | only in doc 
      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 (a] gmail.com}\\
     77 WWW: \URL{http://www.nongnu.org/libunwind/}.
     78 \LatexManEnd
     79 
     80 \end{document}
     81