(Logical change 1.133)

doc/unw_get_proc_info_by_ip.man

@@ -0,0 +1,136 @@
+'\" t
+.\" Manual page created with latex2man on Wed Dec  3 16:36:46 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\\_BY\\_IP" "3" "03 December 2003" "Programming Library " "Programming Library "
+.SH NAME
+unw_get_proc_info_by_ip
+\-\- get procedure info by IP 
+.PP
+.SH SYNOPSIS
+
+.PP
+#include <libunwind.h>
+.br
+.PP
+int
+unw_get_proc_info_by_ip(unw_addr_space_t as,
+unw_word_t ip,
+unw_proc_info_t *pip,
+void *arg);
+.br
+.PP
+.SH DESCRIPTION
+
+.PP
+The unw_get_proc_info_by_ip()
+routine returns the same 
+kind of auxiliary information about a procedure as 
+unw_get_proc_info(),
+except that the info is looked up by 
+instruction\-pointer (IP) instead of a cursor. This is more flexible 
+because it is possible to look up the info for an arbitrary procedure, 
+even if it is not part of the current call\-chain. However, since it 
+is more flexible, it also tends to run slower (and often much slower) 
+than unw_get_proc_info().
+.PP
+The routine expects the followins arguments: as
+is the 
+address\-space in which the instruction\-pointer should be looked up. 
+For a look\-up in the local address\-space, 
+unw_local_addr_space
+can be passed for this argument. 
+Argument ip
+is the instruction\-pointer for which the procedure 
+info should be looked up and pip
+is a pointer to a structure of 
+type unw_proc_info_t
+which is used to return the info. 
+Lastly, arg
+is the address\-space argument that should be used 
+when accessing the address\-space. It has the same purpose as the 
+argument of the same name for unw_init_remote().
+When 
+accessing the local address\-space (first argument is 
+unw_local_addr_space),
+NULL
+must be passed for this 
+argument. 
+.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_by_ip()
+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),
+unw_get_proc_info(3),
+unw_init_remote(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.

doc/unw_get_proc_info_by_ip.tex

@@ -0,0 +1,92 @@
+\documentclass{article}
+\usepackage[fancyhdr,pdf]{latex2man}
+
+\input{common.tex}
+
+\begin{document}
+
+\begin{Name}{3}{unw\_get\_proc\_info\_by\_ip}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_info\_by\_ip}unw\_get\_proc\_info\_by\_ip -- get procedure info by IP
+\end{Name}
+
+\section{Synopsis}
+
+\File{\#include $<$libunwind.h$>$}\\
+
+\Type{int} \Func{unw\_get\_proc\_info\_by\_ip}(\Type{unw\_addr\_space\_t~}\Var{as}, \Type{unw\_word\_t~}\Var{ip}, \Type{unw\_proc\_info\_t~*}\Var{pip}, \Type{void~*}\Var{arg});\\
+
+\section{Description}
+
+The \Func{unw\_get\_proc\_info\_by\_ip}() routine returns the same
+kind of auxiliary information about a procedure as
+\Func{unw\_get\_proc\_info}(), except that the info is looked up by
+instruction-pointer (IP) instead of a cursor.  This is more flexible
+because it is possible to look up the info for an arbitrary procedure,
+even if it is not part of the current call-chain.  However, since it
+is more flexible, it also tends to run slower (and often much slower)
+than \Func{unw\_get\_proc\_info}().
+
+The routine expects the followins arguments: \Var{as} is the
+address-space in which the instruction-pointer should be looked up.
+For a look-up in the local address-space,
+\Var{unw\_local\_addr\_space} can be passed for this argument.
+Argument \Var{ip} is the instruction-pointer for which the procedure
+info should be looked up and \Var{pip} is a pointer to a structure of
+type \Type{unw\_proc\_info\_t} which is used to return the info.
+Lastly, \Var{arg} is the address-space argument that should be used
+when accessing the address-space.  It has the same purpose as the
+argument of the same name for \Func{unw\_init\_remote}().  When
+accessing the local address-space (first argument is
+\Var{unw\_local\_addr\_space}), \Const{NULL} must be passed for this
+argument.
+
+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\_by\_ip}()
+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)},
+\SeeAlso{unw\_get\_proc\_info(3)},
+\SeeAlso{unw\_init\_remote(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}

src/Gget_proc_info_by_ip.c

@@ -0,0 +1,41 @@
+/* libunwind - a platform-independent unwind library
+   Copyright (C) 2003 Hewlett-Packard Co
+	Contributed by David Mosberger-Tang <davidm@hpl.hp.com>
+
+This file is part of libunwind.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.  */
+
+#include <libunwind.h>
+
+#include "internal.h"
+#include "tdep.h"
+
+int
+unw_get_proc_info_by_ip (unw_addr_space_t as, unw_word_t ip,
+			 unw_proc_info_t *pi, void *as_arg)
+{
+  int ret;
+
+  ret = unwi_find_dynamic_proc_info (as, ip, pi, 0, as_arg);
+  if (ret == -UNW_ENOINFO)
+    ret = tdep_find_proc_info (as, ip, pi, 0, as_arg);
+  return ret;
+}

src/Lget_proc_info_by_ip.c

@@ -0,0 +1,5 @@
+#define UNW_LOCAL_ONLY
+#include <libunwind.h>
+#if defined(UNW_LOCAL_ONLY) && !defined(UNW_REMOTE_ONLY)
+#include "Gget_proc_info_by_ip.c"
+#endif