fielding 98/10/09 12:35:52
Modified: . debugging.html
Log:
Describe how to use gdb so that we can point to this file when
users ask questions or report problems.
Revision Changes Path
1.2 +135 -2 apache-devsite/debugging.html
Index: debugging.html
===================================================================
RCS file: /export/home/cvs/apache-devsite/debugging.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- debugging.html 1998/04/20 05:50:13 1.1
+++ debugging.html 1998/10/09 19:35:51 1.2
@@ -1,6 +1,16 @@
-<HTML><HEAD>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
<TITLE>Apache Debugging Guide</TITLE>
-</HEAD><BODY>
+</HEAD>
+<!-- Background white, links blue (unvisited), navy (visited), red (active)
-->
+<BODY
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#000080"
+ALINK="#FF0000"
+>
<H1>Apache Debugging Guide</H1>
@@ -16,10 +26,133 @@
<P><A NAME="gdb"><B>Using '<CODE>gdb</CODE>'</B></A>
+<P>If you use the gcc or egcs compilers, it is likely that the best
+debugger for your system is gdb. This is only a brief summary of how
+to run gdb on Apache -- you should look at the info and man files for
+gdb to get more information on gdb commands and common debugging techniques.
+Before running gdb, be sure that the server is compiled with the
+<CODE>-g</CODE> option in <CODE>EXTRA_CFLAGS</CODE> to include the
+symbol information in the object files.
+
+<P>The only tricky part of running gdb on Apache is forcing the server
+into a single-process mode so that the parent process being debugged
+does the request-handling work instead of forking child processes.
+We have provided the <CODE>-X</CODE> option for that purpose.
+
+<P>The following example, with <font color=green>user input in green</font>,
+shows the output of gdb run on a server executable (httpd) in the current
+working directory and using the server root of
<CODE>/usr/local/apache</CODE>:
+<PRE>
+ % <font color=green>gdb httpd</font>
+ GDB is free software and you are welcome to distribute copies of it
+ under certain conditions; type "show copying" to see the conditions.
+ There is absolutely no warranty for GDB; type "show warranty" for
details.
+ GDB 4.16.gnat.1.13 (sparc-sun-solaris2.5),
+ Copyright 1996 Free Software Foundation, Inc...
+ (gdb) <font color=green>b ap_process_request</font>
+ Breakpoint 1 at 0x49fb4: file http_request.c, line 1164.
+ (gdb) <font color=green>run -X -d /usr/local/apache</font>
+ Starting program: /usr/local/apache/src/httpd -X -d /usr/local/apache
+
+ [at this point I make a request from another window]
+
+ Breakpoint 1, ap_process_request (r=0x95250) at http_request.c:1164
+ 1164 if (ap_extended_status)
+ (gdb) <font color=green>s</font>
+ 1165 ap_time_process_request(r->connection->child_num,
START_PREQUEST);
+ (gdb) <font color=green>n</font>
+ 1167 process_request_internal(r);
+ (gdb) <font color=green>s</font>
+ process_request_internal (r=0x95250) at http_request.c:1028
+ 1028 if (!r->proxyreq && r->parsed_uri.path) {
+ (gdb) <font color=green>s</font>
+ 1029 access_status = ap_unescape_url(r->parsed_uri.path);
+ (gdb) <font color=green>n</font>
+ 1030 if (access_status) {
+ (gdb) <font color=green>s</font>
+ 1036 ap_getparents(r->uri); /* OK --- shrinking
transformations... */
+ (gdb) <font color=green>n</font>
+ 1038 if ((access_status = location_walk(r))) {
+ (gdb) <font color=green>n</font>
+ 1043 if ((access_status = ap_translate_name(r))) {
+ (gdb) <font color=green>n</font>
+ 1048 if (!r->proxyreq) {
+ (gdb) <font color=green>n</font>
+ 1053 if (r->method_number == M_TRACE) {
+ (gdb) <font color=green>n</font>
+ 1062 if (r->proto_num > HTTP_VERSION(1,0) &&
ap_table_get(r->subprocess_env, "downgrade-1.0")) {
+ (gdb) <font color=green>n</font>
+ 1071 if ((access_status = directory_walk(r))) {
+ (gdb) <font color=green>s</font>
+ directory_walk (r=0x95250) at http_request.c:288
+ 288 core_server_config *sconf =
ap_get_module_config(r->server->module_config,
+ (gdb) <font color=green>b ap_send_error_response</font>
+ Breakpoint 2 at 0x47dcc: file http_protocol.c, line 2090.
+ (gdb) <font color=green>c</font>
+ Continuing.
+
+ Breakpoint 2, ap_send_error_response (r=0x95250, recursive_error=0)
+ at http_protocol.c:2090
+ 2090 BUFF *fd = r->connection->client;
+ (gdb) <font color=green>where</font>
+ #0 ap_send_error_response (r=0x95250, recursive_error=0)
+ at http_protocol.c:2090
+ #1 0x49b10 in ap_die (type=403, r=0x95250) at http_request.c:989
+ #2 0x49b60 in decl_die (status=403, phase=0x62db8 "check access",
r=0x95250)
+ at http_request.c:1000
+ #3 0x49f68 in process_request_internal (r=0x95250) at
http_request.c:1141
+ #4 0x49fe0 in ap_process_request (r=0x95250) at http_request.c:1167
+ #5 0x439d8 in child_main (child_num_arg=550608) at http_main.c:3826
+ #6 0x43b5c in make_child (s=0x7c3e8, slot=0, now=907958743)
+ at http_main.c:3898
+ #7 0x43ca8 in startup_children (number_to_start=6) at http_main.c:3972
+ #8 0x44260 in standalone_main (argc=392552, argv=0x75800) at
http_main.c:4250
+ #9 0x449fc in main (argc=4, argv=0xefffee8c) at http_main.c:4534
+ (gdb) <font color=green>s</font>
+ 2091 int status = r->status;
+ (gdb) <font color=green>p status</font>
+ $1 = 403
+ (gdb)
+</PRE>
+
+<P>There are a few things to note about the above example:
+<OL>
+<LI>the "<CODE>gdb httpd</CODE>" command does not include any command-line
+ options for httpd: those are provided when the "<CODE>run</CODE>" command
+ is done within gdb;
+<LI>I set a breakpoint before starting the run so that execution would stop
+ at the top of ap_process_request();
+<LI>the "<CODE>s</CODE>" command steps through the code and into called
+ procedures, whereas the "<CODE>n</CODE>" (next) command steps through
+ the code but not into called procedures.
+<LI>additional breakpoints can be set with the "<CODE>b</CODE>" command,
+ and the run continued with the "<CODE>c</CODE>" command.
+<LI>use the "<CODE>where</CODE>" command (a.k.a. "<CODE>bt</CODE>") to see
+ a stack backtrace that shows the order of called procedures and their
+ parameter values.
+<LI>use the "<CODE>p</CODE>" command to print the value of a variable.
+</OL>
+
<P>A file in the <CODE>src/</CODE> directory, <CODE>.gdbinit</CODE>,
provides a useful macro for printing out the contents of a table
structure, called <CODE>dump_table</CODE>.
+<P>If you are debugging a repeatable crash, simply run gdb as above
+and make the request -- gdb should capture the crash and provide a
+prompt where it occurs.
+
+<P>If you are debugging an apparent infinite loop, simply run gdb as above
+and type a Control-C -- gdb will interrupt the process and provide a
+prompt where it was stopped.
+
+<P>If you are debugging a system crash and you have a core file from
+the crash, then do the following:
+<PRE>
+ % gdb httpd -c core
+ (gdb) where
+</PRE>
+and it will (hopefully) print a stack backtrace of where the core dump
+occurred during processing.
<P>
<HR>
