m2-internship/libunwind-eh_elf
1
0
Fork 0
mirror of https://github.com/tobast/libunwind-eh_elf.git synced 2024-11-26 09:07:38 +01:00
Code Issues Releases Activity

(Logical change 1.62)

Browse source
This commit is contained in:
mostang.com!davidm 2003-03-13 02:15:01 +00:00
parent 5b83414923
commit 27988406b2
12 changed files with 1176 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

97
doc/unw_flush_cache.man Normal file
View file

@ -0,0 +1,97 @@
'\" t
.\" Manual page created with latex2man on Wed Mar 12 14:44:22 PST 2003
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "UNW\\_FLUSH\\_CACHE" "3" "12 March 2003" "Programming Library " "Programming Library "
.SH NAME
.PP
unw_flush_cache \-\- flush cached info
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
void
unw_flush_cache(unw_addr_space_t
as,
unw_word_t
lo,
unw_word_t
hi);
.br
.PP
.SH DESCRIPTION
.PP
The unw_flush_cache()
routine flushes all cached info as it
relates to address\-range lo
to hi
(non\-inclusive) in the
target address\-space as\&.
In addition, all info cached for
address\-space as
that is not tied to a particular code\-range is
also flushed. For example, the address of the dynamic registration
list is not tied to a code\-range and its cached value (if any) is
flushed by a call to this routine. The address range specified by
lo
and hi
should be understood as a hint:
unw_flush_cache()
may flush more information than requested,
but \fInever\fP
less. In other words, unw_flush_cache()
may
overflush, but not underflush.
.PP
As a special case, if arguments lo
and hi
are both 0, all
information cached on behalf of address space as
is flushed.
.PP
.SH RETURN VALUE
.PP
The unw_flush_cache()
routine cannot fail and does not
return a value.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
The unw_flush_cache()
routine is thread\-safe as well as safe to
use from a signal handler.
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_set_caching_policy(3)
.PP
.SH AUTHOR
.PP
David Mosberger\-Tang
.br
Hewlett\-Packard Labs
.br
Palo\-Alto, CA 94304
.br
Email: \fBdavidm@hpl.hp.com\fP
.br
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
.\" NOTE: This file is generated, DO NOT EDIT.

61
doc/unw_flush_cache.tex Normal file
View file

@ -0,0 +1,61 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_flush\_cache}{David Mosberger-Tang}{Programming Library}{unw\_flush\_cache}
unw\_flush\_cache -- flush cached info
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{void} \Func{unw\_flush\_cache}(\Type{unw\_addr\_space\_t} \Var{as}, \Type{unw\_word\_t} \Var{lo}, \Type{unw\_word\_t} \Var{hi});\\
\section{Description}
The \Func{unw\_flush\_cache}() routine flushes all cached info as it
relates to address-range \Var{lo} to \Var{hi} (non-inclusive) in the
target address-space \Var{as}. In addition, all info cached for
address-space \Var{as} that is not tied to a particular code-range is
also flushed. For example, the address of the dynamic registration
list is not tied to a code-range and its cached value (if any) is
flushed by a call to this routine. The address range specified by
\Var{lo} and \Var{hi} should be understood as a hint:
\Func{unw\_flush\_cache}() may flush more information than requested,
but \emph{never} less. In other words, \Func{unw\_flush\_cache}() may
overflush, but not underflush.
As a special case, if arguments \Var{lo} and \Var{hi} are both 0, all
information cached on behalf of address space \Var{as} is flushed.
\section{Return Value}
The \Func{unw\_flush\_cache}() routine cannot fail and does not
return a value.
\section{Thread and Signal Safety}
The \Func{unw\_flush\_cache}() routine is thread-safe as well as safe to
use from a signal handler.
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_set\_caching\_policy(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Hewlett-Packard Labs\\
Palo-Alto, CA 94304\\
Email: \Email{davidm@hpl.hp.com}\\
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
\LatexManEnd
\end{document}

84
doc/unw_get_accessors.man Normal file
View file

@ -0,0 +1,84 @@
'\" t
.\" Manual page created with latex2man on Wed Mar 12 14:20:21 PST 2003
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "UNW\\_GET\\_ACCESSORS" "3" "12 March 2003" "Programming Library " "Programming Library "
.SH NAME
.PP
unw_get_accessors \-\- get pointer to accessor call\-backs
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
unw_accessors_t *unw_get_accessors(unw_addr_space_t as);
.br
.PP
.SH DESCRIPTION
.PP
The unw_get_accessors()
routine returns a pointer to a
unw_accessors_t
structure, which contains the call\-back
routines that were specified when address space as
was created
(see unw_create_addr_space(3)).
The returned pointer is
guaranteed to remain valid until address space as
is destroyed
by a call to unw_destroy_addr_space(3).
.PP
Note that unw_get_accessors()
can be used to retrieve the
call\-back routines for the local address space
unw_local_addr_space\&.
.PP
.SH RETURN VALUE
.PP
The unw_get_accessors()
routine cannot fail and always
returns a valid (non\-NULL)
pointer to an
unw_accessors_t
structure.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
The unw_get_accessors()
routine is thread\-safe as well as
safe to use from a signal handler.
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_create_addr_space(3),
unw_destroy_addr_space(3)
.PP
.SH AUTHOR
.PP
David Mosberger\-Tang
.br
Hewlett\-Packard Labs
.br
Palo\-Alto, CA 94304
.br
Email: \fBdavidm@hpl.hp.com\fP
.br
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
.\" NOTE: This file is generated, DO NOT EDIT.

59
doc/unw_get_accessors.tex Normal file
View file

@ -0,0 +1,59 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_get\_accessors}{David Mosberger-Tang}{Programming Library}{unw\_get\_accessors}
unw\_get\_accessors -- get pointer to accessor call-backs
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{unw\_accessors\_t~*}\Func{unw\_get\_accessors}(\Type{unw\_addr\_space\_t~}\Var{as});\\
\section{Description}
The \Func{unw\_get\_accessors}() routine returns a pointer to a
\Type{unw\_accessors\_t} structure, which contains the call-back
routines that were specified when address space \Var{as} was created
(see \Func{unw\_create\_addr\_space}(3)). The returned pointer is
guaranteed to remain valid until address space \Var{as} is destroyed
by a call to \Func{unw\_destroy\_addr\_space}(3).
Note that \Func{unw\_get\_accessors}() can be used to retrieve the
call-back routines for the local address space
\Var{unw\_local\_addr\_space}.
\section{Return Value}
The \Func{unw\_get\_accessors}() routine cannot fail and always
returns a valid (non-\Const{NULL}) pointer to an
\Type{unw\_accessors\_t} structure.
\section{Thread and Signal Safety}
The \Func{unw\_get\_accessors}() routine is thread-safe as well as
safe to use from a signal handler.
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_create\_addr\_space(3)},
\SeeAlso{unw\_destroy\_addr\_space(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Hewlett-Packard Labs\\
Palo-Alto, CA 94304\\
Email: \Email{davidm@hpl.hp.com}\\
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
\LatexManEnd
\end{document}

206
doc/unw_get_proc_info.man Normal file
View file

@ -0,0 +1,206 @@
'\" t
.\" Manual page created with latex2man on Wed Mar 12 12:27:22 PST 2003
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "UNW\\_GET\\_PROC\\_INFO" "3" "12 March 2003" "Programming Library " "Programming Library "
.SH NAME
.PP
unw_get_proc_info \-\- get info on current procedure
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_get_proc_info(unw_cursor_t *cp,
unw_proc_info_t *pip);
.br
.PP
.SH DESCRIPTION
.PP
The unw_get_proc_info()
routine returns auxiliary
information about the procedure that created the stack frame
identified by argument cp\&.
The pip
argument is a pointer
to a structure of type unw_proc_info_t
which is used to
return the information. The unw_proc_info_t
has the
following members:
.TP
unw_word_t start_ip
The address of the first
instruction of the procedure. If this address cannot be determined
(e.g., due to lack of unwind information), the start_ip
member is cleared to 0.
.br
.TP
unw_word_t end_ip
The address of the first
instruction \fIbeyond\fP
the end of the procedure. If this address
cannot be determined (e.g., due to lack of unwind information),
the end_ip
member is cleared to 0.
.br
.TP
unw_word_t lsda
The address of the
language\-specific data\-area (LSDA). This area normally contains
language\-specific information needed during exception handling. If
the procedure has no such area, this member is cleared to 0.
.br
.TP
unw_word_t handler
The address of the exception
handler routine. This is sometimes called the \fIpersonality\fP
routine. If the procedure does not define
a personality routine, the handler
member is cleared to 0.
.br
.TP
unw_word_t gp
The global\-pointer of the
procedure. On platforms that do not use a global pointer, this
member may contain an undefined value. On all other platforms, it
must be set either to the correct global\-pointer value of the
procedure or to 0 if the proper global\-pointer cannot be
obtained for some reason.
.br
.TP
unw_word_t flags
A set of flags. There are
currently no target\-independent flags. For the IA\-64 target, the
flag UNW_PI_FLAG_IA64_RBS_SWITCH
is set if the
procedure may switch the register\-backing store.
.br
.TP
int format
The format of the unwind\-info for this
procedure. If the unwind\-info consists of dynamic procedure info,
format
is equal to UNW_INFO_FORMAT_DYNAMIC\&.
If the
unwind\-info consists of a (target\-specific) unwind table, it is
equal to to UNW_INFO_FORMAT_TABLE\&.
All other values are
reserved for future use by libunwind\&.
This member exists
for use by the find_proc_info()
call\-back (see
unw_create_addr_space(3)).
The
unw_get_proc_info()
routine
may return an undefined value in this member.
.br
.TP
int unwind_info_size
The size of the unwind\-info
in bytes. This member exists for use by the
find_proc_info()
call\-back (see
unw_create_addr_space(3)).
The
unw_get_proc_info()
routine
may return an undefined value in this member.
.br
.TP
void *unwind_info
The pointer to the unwind\-info.
If no unwind info is available, this member must be set to
NULL\&.
This member exists for use by the
find_proc_info()
call\-back (see
unw_create_addr_space(3)).
The
unw_get_proc_info()
routine
may return an undefined value in this member.
.br
.PP
Note that for the purposes of libunwind,
the code of a
procedure is assumed to occupy a single, contiguous range of
addresses. For this reason, it is alwas possible to describe the
extent of a procedure with the start_ip
and end_ip
members. If a single function/routine is split into multiple,
discontiguous pieces, libunwind
will treat each piece as a
separate procedure.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_get_proc_info()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_get_proc_info()
is thread\-safe as well as safe to use
from a signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_EUNSPEC
An unspecified error occurred.
.TP
UNW_ENOINFO
Libunwind
was unable to locate
unwind\-info for the procedure.
.TP
UNW_EBADVERSION
The unwind\-info for the procedure has
version or format that is not understood by libunwind\&.
.PP
In addition, unw_get_proc_info()
may return any error
returned by the access_mem()
call\-back (see
unw_create_addr_space(3)).
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_create_addr_space(3),
unw_get_proc_name(3)
.PP
.SH AUTHOR
.PP
David Mosberger\-Tang
.br
Hewlett\-Packard Labs
.br
Palo\-Alto, CA 94304
.br
Email: \fBdavidm@hpl.hp.com\fP
.br
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
.\" NOTE: This file is generated, DO NOT EDIT.

126
doc/unw_get_proc_info.tex Normal file
View file

@ -0,0 +1,126 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_get\_proc\_info}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_info}
unw\_get\_proc\_info -- get info on current procedure
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_proc\_info\_t~*}\Var{pip});\\
\section{Description}
The \Func{unw\_get\_proc\_info}() routine returns auxiliary
information about the procedure that created the stack frame
identified by argument \Var{cp}. The \Var{pip} argument is a pointer
to a structure of type \Type{unw\_proc\_info\_t} which is used to
return the information. The \Type{unw\_proc\_info\_t} has the
following members:
\begin{description}
\item[\Type{unw\_word\_t} \Var{start\_ip}] The address of the first
instruction of the procedure. If this address cannot be determined
(e.g., due to lack of unwind information), the \Var{start\_ip}
member is cleared to 0. \\
\item[\Type{unw\_word\_t} \Var{end\_ip}] The address of the first
instruction \emph{beyond} the end of the procedure. If this address
cannot be determined (e.g., due to lack of unwind information),
the \Var{end\_ip} member is cleared to 0. \\
\item[\Type{unw\_word\_t} \Var{lsda}] The address of the
language-specific data-area (LSDA). This area normally contains
language-specific information needed during exception handling. If
the procedure has no such area, this member is cleared to 0. \\
\item[\Type{unw\_word\_t} \Var{handler}] The address of the exception
handler routine. This is sometimes called the \emph{personality}
routine. If the procedure does not define
a personality routine, the \Var{handler} member is cleared to 0. \\
\item[\Type{unw\_word\_t} \Var{gp}] The global-pointer of the
procedure. On platforms that do not use a global pointer, this
member may contain an undefined value. On all other platforms, it
must be set either to the correct global-pointer value of the
procedure or to 0 if the proper global-pointer cannot be
obtained for some reason. \\
\item[\Type{unw\_word\_t} \Var{flags}] A set of flags. There are
currently no target-independent flags. For the IA-64 target, the
flag \Const{UNW_PI_FLAG_IA64_RBS_SWITCH} is set if the
procedure may switch the register-backing store.\\
\item[\Type{int} \Var{format}] The format of the unwind-info for this
procedure. If the unwind-info consists of dynamic procedure info,
\Var{format} is equal to \Const{UNW\_INFO\_FORMAT\_DYNAMIC}. If the
unwind-info consists of a (target-specific) unwind table, it is
equal to to \Const{UNW\_INFO\_FORMAT\_TABLE}. All other values are
reserved for future use by \Prog{libunwind}. This member exists
for use by the \Func{find\_proc\_info}() call-back (see
\Func{unw\_create\_addr\_space}(3)). The
\Func{unw\_get\_proc\_info}() routine
may return an undefined value in this member. \\
\item[\Type{int} \Var{unwind\_info\_size}] The size of the unwind-info
in bytes. This member exists for use by the
\Func{find\_proc\_info}() call-back (see
\Func{unw\_create\_addr\_space}(3)). The
\Func{unw\_get\_proc\_info}() routine
may return an undefined value in this member.\\
\item[\Type{void~*}\Var{unwind\_info}] The pointer to the unwind-info.
If no unwind info is available, this member must be set to
\Const{NULL}. This member exists for use by the
\Func{find\_proc\_info}() call-back (see
\Func{unw\_create\_addr\_space}(3)). The
\Func{unw\_get\_proc\_info}() routine
may return an undefined value in this member.\\
\end{description}
Note that for the purposes of \Prog{libunwind}, the code of a
procedure is assumed to occupy a single, contiguous range of
addresses. For this reason, it is alwas possible to describe the
extent of a procedure with the \Var{start\_ip} and \Var{end\_ip}
members. If a single function/routine is split into multiple,
discontiguous pieces, \Prog{libunwind} will treat each piece as a
separate procedure.
\section{Return Value}
On successful completion, \Func{unw\_get\_proc\_info}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_get\_proc\_info}() is thread-safe as well as safe to use
from a signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate
unwind-info for the procedure.
\item[\Const{UNW\_EBADVERSION}] The unwind-info for the procedure has
version or format that is not understood by \Prog{libunwind}.
\end{Description}
In addition, \Func{unw\_get\_proc\_info}() may return any error
returned by the \Func{access\_mem}() call-back (see
\Func{unw\_create\_addr\_space}(3)).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_create\_addr\_space(3)},
\SeeAlso{unw\_get\_proc\_name(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Hewlett-Packard Labs\\
Palo-Alto, CA 94304\\
Email: \Email{davidm@hpl.hp.com}\\
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
\LatexManEnd
\end{document}

127
doc/unw_get_proc_name.man Normal file
View file

@ -0,0 +1,127 @@
'\" t
.\" Manual page created with latex2man on Wed Mar 12 12:55:19 PST 2003
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "UNW\\_GET\\_PROC\\_NAME" "3" "12 March 2003" "Programming Library " "Programming Library "
.SH NAME
.PP
unw_get_proc_name \-\- get name of current procedure
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_get_proc_name(unw_cursor_t *cp,
char *bufp,
size_t
len,
unw_word_t *offp);
.br
.PP
.SH DESCRIPTION
.PP
The unw_get_proc_name()
routine returns the name of the
procedure that created the stack frame identified by argument
cp\&.
The bufp
argument is a pointer to a character buffer
that is at least len
bytes long. This buffer is used to return
the name of the procedure. The offp
argument is a pointer to a
word that is used to return the byte\-offset of the instruction\-pointer
saved in the stack frame identified by cp,
relative to the start
of the procedure. For example, if procedure foo()
starts at
address 0x40003000, then invoking unw_get_proc_name()
on a
stack frame with an instruction\-pointer value of 0x40003080 would
return a value of 0x80 in the word pointed to by offp
(assuming
the procedure is at least 0x80 bytes long).
.PP
Note that on some platforms there is no reliable way to distinguish
between procedure names and ordinary labels. Furthermore, if symbol
information has been stripped from a program, procedure names may be
completely unavailable or may be limited to those exported via a
dynamic symbol table. In such cases, unw_get_proc_name()
may return the name of a label or a preceeding (nearby) procedure.
However, the offset returned through offp
is always relative to
the returned name, which ensures that the value (address) of the
returned name plus the returned offset will always be equal to the
instruction\-pointer of the stack frame identified by cp\&.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_get_proc_name()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_get_proc_name()
is thread\-safe but \fInot\fP
safe to
use from a signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_EUNSPEC
An unspecified error occurred.
.TP
UNW_ENOINFO
Libunwind
was unable to determine
the name of the procedure.
.TP
UNW_ENOMME
The procedure name is too long to fit
in the buffer provided. A truncated version of the name has been
returned.
.PP
In addition, unw_get_proc_name()
may return any error
returned by the access_mem()
call\-back (see
unw_create_addr_space(3)).
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_get_proc_info(3)
.PP
.SH AUTHOR
.PP
David Mosberger\-Tang
.br
Hewlett\-Packard Labs
.br
Palo\-Alto, CA 94304
.br
Email: \fBdavidm@hpl.hp.com\fP
.br
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
.\" NOTE: This file is generated, DO NOT EDIT.

85
doc/unw_get_proc_name.tex Normal file
View file

@ -0,0 +1,85 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_get\_proc\_name}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_name}
unw\_get\_proc\_name -- get name of current procedure
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_get\_proc\_name}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{char~*}\Var{bufp}, \Type{size\_t} \Var{len}, \Type{unw\_word\_t~*}\Var{offp});\\
\section{Description}
The \Func{unw\_get\_proc\_name}() routine returns the name of the
procedure that created the stack frame identified by argument
\Var{cp}. The \Var{bufp} argument is a pointer to a character buffer
that is at least \Var{len} bytes long. This buffer is used to return
the name of the procedure. The \Var{offp} argument is a pointer to a
word that is used to return the byte-offset of the instruction-pointer
saved in the stack frame identified by \Var{cp}, relative to the start
of the procedure. For example, if procedure \Func{foo}() starts at
address 0x40003000, then invoking \Func{unw\_get\_proc\_name}() on a
stack frame with an instruction-pointer value of 0x40003080 would
return a value of 0x80 in the word pointed to by \Var{offp} (assuming
the procedure is at least 0x80 bytes long).
Note that on some platforms there is no reliable way to distinguish
between procedure names and ordinary labels. Furthermore, if symbol
information has been stripped from a program, procedure names may be
completely unavailable or may be limited to those exported via a
dynamic symbol table. In such cases, \Func{unw\_get\_proc\_name}()
may return the name of a label or a preceeding (nearby) procedure.
However, the offset returned through \Var{offp} is always relative to
the returned name, which ensures that the value (address) of the
returned name plus the returned offset will always be equal to the
instruction-pointer of the stack frame identified by \Var{cp}.
\section{Return Value}
On successful completion, \Func{unw\_get\_proc\_name}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_get\_proc\_name}() is thread-safe but \emph{not} safe to
use from a signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to determine
the name of the procedure.
\item[\Const{UNW\_ENOMME}] The procedure name is too long to fit
in the buffer provided. A truncated version of the name has been
returned.
\end{Description}
In addition, \Func{unw\_get\_proc\_name}() may return any error
returned by the \Func{access\_mem}() call-back (see
\Func{unw\_create\_addr\_space}(3)).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_get\_proc\_info(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Hewlett-Packard Labs\\
Palo-Alto, CA 94304\\
Email: \Email{davidm@hpl.hp.com}\\
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
\LatexManEnd
\end{document}

73
doc/unw_regname.man Normal file
View file

@ -0,0 +1,73 @@
'\" t
.\" Manual page created with latex2man on Wed Mar 12 14:22:15 PST 2003
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "UNW\\_REGNAME" "3" "12 March 2003" "Programming Library " "Programming Library "
.SH NAME
.PP
unw_regname \-\- get register name
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
const char *unw_regname(unw_regnum_t
regnum);
.br
.PP
.SH DESCRIPTION
.PP
The unw_regname()
routine returns a printable name for
register regnum\&.
If regnum
is an invalid or otherwise
unrecognized register number, a string consisting of three question
marks is returned. The returned string is statically allocated and
therefore guaranteed to remain valid until the application terminates.
.PP
.SH RETURN VALUE
.PP
The unw_regname()
routine cannot fail and always returns a
valid (non\-NULL)
string.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
The unw_regname()
routine is thread\-safe as well as safe to
use from a signal handler.
.PP
.SH SEE ALSO
.PP
libunwind(3)
.PP
.SH AUTHOR
.PP
David Mosberger\-Tang
.br
Hewlett\-Packard Labs
.br
Palo\-Alto, CA 94304
.br
Email: \fBdavidm@hpl.hp.com\fP
.br
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
.\" NOTE: This file is generated, DO NOT EDIT.

51
doc/unw_regname.tex Normal file
View file

@ -0,0 +1,51 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_regname}{David Mosberger-Tang}{Programming Library}{unw\_regname}
unw\_regname -- get register name
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{const char~*}\Func{unw\_regname}(\Type{unw\_regnum\_t} \Var{regnum});\\
\section{Description}
The \Func{unw\_regname}() routine returns a printable name for
register \Var{regnum}. If \Var{regnum} is an invalid or otherwise
unrecognized register number, a string consisting of three question
marks is returned. The returned string is statically allocated and
therefore guaranteed to remain valid until the application terminates.
\section{Return Value}
The \Func{unw\_regname}() routine cannot fail and always returns a
valid (non-\Const{NULL}) string.
\section{Thread and Signal Safety}
The \Func{unw\_regname}() routine is thread-safe as well as safe to
use from a signal handler.
\section{See Also}
\SeeAlso{libunwind(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Hewlett-Packard Labs\\
Palo-Alto, CA 94304\\
Email: \Email{davidm@hpl.hp.com}\\
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
\LatexManEnd
\end{document}

123
doc/unw_set_caching_policy.man Normal file
View file

@ -0,0 +1,123 @@
'\" t
.\" Manual page created with latex2man on Wed Mar 12 18:06:37 PST 2003
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "UNW\\_SET\\_CACHING\\_POLICY" "3" "12 March 2003" "Programming Library " "Programming Library "
.SH NAME
.PP
unw_set_caching_policy \-\- set unwind caching policy
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_set_caching_policy(unw_addr_space_t
as,
unw_caching_policy_t
policy);
.br
.PP
.SH DESCRIPTION
.PP
The unw_set_caching_policy()
routine sets the caching policy
of address space as
to the policy specified by argument
policy\&.
The policy
argument can take one of three
possible values:
.TP
UNW_CACHE_NONE
Turns off caching completely. This
also implicitly flushes the contents of all caches as if
unw_flush_cache()
had been called.
.TP
UNW_CACHE_GLOBAL
Enables caching using a global cache
that is shared by all threads. If global caching is unavailable or
unsupported, libunwind
may fall back on using a per\-thread
cache, as if UNW_CACHE_PER_THREAD
had been specified.
.TP
UNW_CACHE_PER_THREAD
Enables caching using
thread\-local caches. If a thread\-local caching are unavailable or
unsupported, libunwind
may fall back on using a global cache,
as if UNW_CACHE_GLOBAL
had been specified.
.PP
If caching is enabled, an application must be prepared to make
appropriate calls to 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,
unw_flush_cache()
would have to be called (at least) for the
address\-range that was covered by the shared library.
.PP
For address spaces created via unw_create_addr_space(3),
caching is turned off by default. For the local address space
unw_local_addr_space,
caching is turned on by default.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_set_caching_policy()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_set_caching_policy()
is thread\-safe but \fInot\fP
safe
to use from a signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_ENOMEM
The desired caching policy could not be
established because the application is out of memory.
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_create_addr_space(3),
unw_flush_cache(3)
.PP
.SH AUTHOR
.PP
David Mosberger\-Tang
.br
Hewlett\-Packard Labs
.br
Palo\-Alto, CA 94304
.br
Email: \fBdavidm@hpl.hp.com\fP
.br
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
.\" NOTE: This file is generated, DO NOT EDIT.

84
doc/unw_set_caching_policy.tex Normal file
View file

@ -0,0 +1,84 @@
\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\\
Hewlett-Packard Labs\\
Palo-Alto, CA 94304\\
Email: \Email{davidm@hpl.hp.com}\\
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
\LatexManEnd
\end{document}