/usr/share/doc/glibc-doc/html/libc_33.html is in glibc-doc 2.15-0ubuntu10.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- This file documents the GNU C library.
This is Edition 0.13, last updated 2011-07-19,
of The GNU C Library Reference Manual, for version
2.14 (Ubuntu EGLIBC 2.15-0ubuntu10) .
Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010, 2011 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software Needs Free Documentation"
and "GNU Lesser General Public License", the Front-Cover texts being
"A GNU Manual", and with the Back-Cover Texts as in (a) below. A
copy of the license is included in the section entitled "GNU Free
Documentation License".
(a) The FSF's Back-Cover Text is: "You have the freedom to
copy and modify this GNU manual. Buying copies from the FSF
supports it in developing GNU and promoting software freedom."
-->
<!-- Created on April 20, 2012 by texi2html 1.82
texi2html was written by:
Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>The GNU C Library: 33. Debugging support</title>
<meta name="description" content="The GNU C Library: 33. Debugging support">
<meta name="keywords" content="The GNU C Library: 33. Debugging support">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.82">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Debugging-Support"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="libc_32.html#DES-Encryption" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Backtraces" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc_32.html#Cryptographic-Functions" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_34.html#Language-Features" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Debugging-support"></a>
<h1 class="chapter">33. Debugging support</h1>
<p>Applications are usually debugged using dedicated debugger programs.
But sometimes this is not possible and, in any case, it is useful to
provide the developer with as much information as possible at the time
the problems are experienced. For this reason a few functions are
provided which a program can use to help the developer more easily
locate the problem.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Backtraces">33.1 Backtraces</a></td><td> </td><td align="left" valign="top"> Obtaining and printing a back trace of the
current stack.
</td></tr>
</table>
<hr size="6">
<a name="Backtraces"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Debugging-Support" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="libc_34.html#Language-Features" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Debugging-Support" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Debugging-Support" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_34.html#Language-Features" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Backtraces-1"></a>
<h2 class="section">33.1 Backtraces</h2>
<a name="index-backtrace"></a>
<a name="index-backtrace_005fsymbols"></a>
<a name="index-backtrace_005ffd"></a>
<p>A <em>backtrace</em> is a list of the function calls that are currently
active in a thread. The usual way to inspect a backtrace of a program
is to use an external debugger such as gdb. However, sometimes it is
useful to obtain a backtrace programmatically from within a program,
e.g., for the purposes of logging or diagnostics.
</p>
<p>The header file ‘<tt>execinfo.h</tt>’ declares three functions that obtain
and manipulate backtraces of the current thread.
<a name="index-execinfo_002eh"></a>
</p>
<dl>
<dt><a name="index-backtrace-1"></a><u>Function:</u> int <b>backtrace</b><i> (void **<var>buffer</var>, int <var>size</var>)</i></dt>
<dd><p>The <code>backtrace</code> function obtains a backtrace for the current
thread, as a list of pointers, and places the information into
<var>buffer</var>. The argument <var>size</var> should be the number of
<code>void *</code> elements that will fit into <var>buffer</var>. The return
value is the actual number of entries of <var>buffer</var> that are obtained,
and is at most <var>size</var>.
</p>
<p>The pointers placed in <var>buffer</var> are actually return addresses
obtained by inspecting the stack, one return address per stack frame.
</p>
<p>Note that certain compiler optimizations may interfere with obtaining a
valid backtrace. Function inlining causes the inlined function to not
have a stack frame; tail call optimization replaces one stack frame with
another; frame pointer elimination will stop <code>backtrace</code> from
interpreting the stack contents correctly.
</p></dd></dl>
<dl>
<dt><a name="index-backtrace_005fsymbols-1"></a><u>Function:</u> char ** <b>backtrace_symbols</b><i> (void *const *<var>buffer</var>, int <var>size</var>)</i></dt>
<dd><p>The <code>backtrace_symbols</code> function translates the information
obtained from the <code>backtrace</code> function into an array of strings.
The argument <var>buffer</var> should be a pointer to an array of addresses
obtained via the <code>backtrace</code> function, and <var>size</var> is the number
of entries in that array (the return value of <code>backtrace</code>).
</p>
<p>The return value is a pointer to an array of strings, which has
<var>size</var> entries just like the array <var>buffer</var>. Each string
contains a printable representation of the corresponding element of
<var>buffer</var>. It includes the function name (if this can be
determined), an offset into the function, and the actual return address
(in hexadecimal).
</p>
<p>Currently, the function name and offset only be obtained on systems that
use the ELF binary format for programs and libraries. On other systems,
only the hexadecimal return address will be present. Also, you may need
to pass additional flags to the linker to make the function names
available to the program. (For example, on systems using GNU ld, you
must pass (<code>-rdynamic</code>.)
</p>
<p>The return value of <code>backtrace_symbols</code> is a pointer obtained via
the <code>malloc</code> function, and it is the responsibility of the caller
to <code>free</code> that pointer. Note that only the return value need be
freed, not the individual strings.
</p>
<p>The return value is <code>NULL</code> if sufficient memory for the strings
cannot be obtained.
</p></dd></dl>
<dl>
<dt><a name="index-backtrace_005fsymbols_005ffd"></a><u>Function:</u> void <b>backtrace_symbols_fd</b><i> (void *const *<var>buffer</var>, int <var>size</var>, int <var>fd</var>)</i></dt>
<dd><p>The <code>backtrace_symbols_fd</code> function performs the same translation
as the function <code>backtrace_symbols</code> function. Instead of returning
the strings to the caller, it writes the strings to the file descriptor
<var>fd</var>, one per line. It does not use the <code>malloc</code> function, and
can therefore be used in situations where that function might fail.
</p></dd></dl>
<p>The following program illustrates the use of these functions. Note that
the array to contain the return addresses returned by <code>backtrace</code>
is allocated on the stack. Therefore code like this can be used in
situations where the memory handling via <code>malloc</code> does not work
anymore (in which case the <code>backtrace_symbols</code> has to be replaced
by a <code>backtrace_symbols_fd</code> call as well). The number of return
addresses is normally not very large. Even complicated programs rather
seldom have a nesting level of more than, say, 50 and with 200 possible
entries probably all programs should be covered.
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <execinfo.h>
#include <stdio.h>
#include <stdlib.h>
/* <span class="roman">Obtain a backtrace and print it to <code>stdout</code>.</span> */
void
print_trace (void)
{
void *array[10];
size_t size;
char **strings;
size_t i;
size = backtrace (array, 10);
strings = backtrace_symbols (array, size);
printf ("Obtained %zd stack frames.\n", size);
for (i = 0; i < size; i++)
printf ("%s\n", strings[i]);
free (strings);
}
/* <span class="roman">A dummy function to make the backtrace more interesting.</span> */
void
dummy_function (void)
{
print_trace ();
}
int
main (void)
{
dummy_function ();
return 0;
}
</pre></td></tr></table>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Debugging-Support" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="libc_34.html#Language-Features" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
<font size="-1">
This document was generated by <em>root</em> on <em>April 20, 2012</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html 1.82</em></a>.
</font>
<br>
</p>
</body>
</html>
|