diff --git a/doc/unw_flush_cache.man b/doc/unw_flush_cache.man new file mode 100644 index 00000000..79a07889 --- /dev/null +++ b/doc/unw_flush_cache.man @@ -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 +.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. diff --git a/doc/unw_flush_cache.tex b/doc/unw_flush_cache.tex new file mode 100644 index 00000000..150907fa --- /dev/null +++ b/doc/unw_flush_cache.tex @@ -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} diff --git a/doc/unw_get_accessors.man b/doc/unw_get_accessors.man new file mode 100644 index 00000000..b435770d --- /dev/null +++ b/doc/unw_get_accessors.man @@ -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 +.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. diff --git a/doc/unw_get_accessors.tex b/doc/unw_get_accessors.tex new file mode 100644 index 00000000..a8bd35bb --- /dev/null +++ b/doc/unw_get_accessors.tex @@ -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} diff --git a/doc/unw_get_proc_info.man b/doc/unw_get_proc_info.man new file mode 100644 index 00000000..0eaf24cb --- /dev/null +++ b/doc/unw_get_proc_info.man @@ -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 +.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. diff --git a/doc/unw_get_proc_info.tex b/doc/unw_get_proc_info.tex new file mode 100644 index 00000000..6cb51dde --- /dev/null +++ b/doc/unw_get_proc_info.tex @@ -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} diff --git a/doc/unw_get_proc_name.man b/doc/unw_get_proc_name.man new file mode 100644 index 00000000..7d4c4349 --- /dev/null +++ b/doc/unw_get_proc_name.man @@ -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 +.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. diff --git a/doc/unw_get_proc_name.tex b/doc/unw_get_proc_name.tex new file mode 100644 index 00000000..0be8d1b9 --- /dev/null +++ b/doc/unw_get_proc_name.tex @@ -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} diff --git a/doc/unw_regname.man b/doc/unw_regname.man new file mode 100644 index 00000000..418023cc --- /dev/null +++ b/doc/unw_regname.man @@ -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 +.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. diff --git a/doc/unw_regname.tex b/doc/unw_regname.tex new file mode 100644 index 00000000..f66bfb8d --- /dev/null +++ b/doc/unw_regname.tex @@ -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} diff --git a/doc/unw_set_caching_policy.man b/doc/unw_set_caching_policy.man new file mode 100644 index 00000000..f45ef89d --- /dev/null +++ b/doc/unw_set_caching_policy.man @@ -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 +.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. diff --git a/doc/unw_set_caching_policy.tex b/doc/unw_set_caching_policy.tex new file mode 100644 index 00000000..87eecab9 --- /dev/null +++ b/doc/unw_set_caching_policy.tex @@ -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}