Factor out `hurd/debugging/gdb' and create `hurd/debugging/rpctrace'.

5 files changed, 79 insertions, 17 deletions

diff --git a/hurd/debugging.mdwn b/hurd/debugging.mdwn
index da35d819..3ff2fba4 100644
--- a/hurd/debugging.mdwn
+++ b/hurd/debugging.mdwn
@@ -17,15 +17,9 @@ redistribute your contributions.
 
 # Strategies
 
-* [[subhurd]]
-* [[noninvasivedebugging]]
-
-# The GNU Debugger *GDB*
-
-* [Manual](http://sourceware.org/gdb/documentation/)
-* [Hurd-specific features](http://sourceware.org/gdb/current/onlinedocs/gdb_19.html#Hurd%20Native).
-* [[noninvasivedebugging]]
-* [When disassemble doesn't work](http://lists.gnu.org/archive/html/bug-hurd/2007-02/msg00039.html)
+* [[GDB]] -- the GNU debugger
+* [[subhurd]] -- running another Hurd system in parallel
+* [[rpctrace]] -- tracing [[RPC]]s
 
 
 # About Specific Packages
diff --git a/hurd/debugging/gdb.mdwn b/hurd/debugging/gdb.mdwn
new file mode 100644
index 00000000..75474128
--- /dev/null
+++ b/hurd/debugging/gdb.mdwn
@@ -0,0 +1,26 @@
+[[license text="""
+Copyright © 2007 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.2 or any later version
+published by the Free Software Foundation; with no Invariant Sections, no
+Front-Cover Texts, and no Back-Cover Texts.  A copy of the license is included
+in the section entitled [[GNU_Free_Documentation_License|/fdl.txt]].
+
+By contributing to this page, you agree to assign copyright for your
+contribution to the Free Software Foundation.  The Free Software Foundation
+promises to always use either a verbatim copying license or a free
+documentation license when publishing your contribution.  We grant you back all
+your rights under copyright, including the rights to copy, modify, and
+redistribute your contributions.
+"""]]
+
+The [GNU debugger *GDB*](http://www.gnu.org/software/gdb/) works on GNU/Hurd
+systems as it does on other system, but has some additional [hurd-specific
+features](http://sourceware.org/gdb/current/onlinedocs/gdb_19.html#Hurd%20Native)
+to offer, such as [[noninvasive_debugging]] (for avoiding [[deadlock]]s), for
+example.
+
+* [Manual](http://sourceware.org/gdb/documentation/)
+
+* [When disassemble doesn't work](http://lists.gnu.org/archive/html/bug-hurd/2007-02/msg00039.html)
diff --git a/hurd/noninvasivedebugging.mdwn b/hurd/debugging/gdb/noninvasive_debugging.mdwn
index f2ab8489..fc6653e7 100644
--- a/hurd/noninvasivedebugging.mdwn
+++ b/hurd/debugging/gdb/noninvasive_debugging.mdwn
@@ -15,9 +15,9 @@ your rights under copyright, including the rights to copy, modify, and
 redistribute your contributions.
 """]]
 
-Sometimes using gdb on a server can result in
-deadlock.  You can still use gdb by using
-the "set noninvasive" option.  This indicates
-to gdb to not stop the program but allows you to
-nevertheless examine its state.  Thus, you can get back traces
-and value of variables (and watch them change underneath you).
+Sometimes using [[GDB]] on a system server can result in a [[deadlock]].  You
+can however still use GDB by using the [`set
+noninvasive`](http://sourceware.org/gdb/current/onlinedocs/gdb_19.html#Hurd%20Native)
+option.  This indicates to GDB to not stop the program but allows you to
+nevertheless examine its state.  Thus, you can get back traces and value of
+variables (and watch them change underneath you).
diff --git a/hurd/debugging/rpctrace.mdwn b/hurd/debugging/rpctrace.mdwn
new file mode 100644
index 00000000..c2aabc42
--- /dev/null
+++ b/hurd/debugging/rpctrace.mdwn
@@ -0,0 +1,42 @@
+[[license text="""
+Copyright © 2007 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.2 or any later version
+published by the Free Software Foundation; with no Invariant Sections, no
+Front-Cover Texts, and no Back-Cover Texts.  A copy of the license is included
+in the section entitled [[GNU_Free_Documentation_License|/fdl.txt]].
+
+By contributing to this page, you agree to assign copyright for your
+contribution to the Free Software Foundation.  The Free Software Foundation
+promises to always use either a verbatim copying license or a free
+documentation license when publishing your contribution.  We grant you back all
+your rights under copyright, including the rights to copy, modify, and
+redistribute your contributions.
+"""]]
+
+*rpctrace* is -- roughly -- an equivavlent to Linux's *strace* or Solaris' or
+BSD's *truss*.  It is used to trace [[remote_procedure_call|rpc]]s a process is
+doing.
+
+See `rpctrace --help` about how to use it.
+
+
+# Issues and Patches
+
+* <http://savannah.gnu.org/patch/?2104> -- don't assert that local port names
+  are valid
+* <http://savannah.gnu.org/bugs/?3939> -- `rpctrace`d program hangs when signal
+  that terminates or suspends it is sent
+  * <http://savannah.gnu.org/patch/?1633> -- terminated with `C-c` `rpctrace`d
+    programs hang
+* <http://savannah.gnu.org/patch/?5580> -- more readable output
+* <http://savannah.gnu.org/bugs/?20612> -- heisenbug
+
+
+# TODO
+
+    <youpi> how to rpctrace a translator ?
+    <youpi> ah, just settrans /usr/bin/rpctrace...
+    <youpi> hum, it hung, and killing it got a Mach panic (thread in unexpected
+      state) ...
diff --git a/hurd/subhurd.mdwn b/hurd/subhurd.mdwn
index 758450f7..5256a70b 100644
--- a/hurd/subhurd.mdwn
+++ b/hurd/subhurd.mdwn
@@ -23,8 +23,8 @@ Sub-hurds are extremely useful for debugging core servers as it is possible to
 attach to them with gdb from the parent
 ([[debugging_via_subhurds|debugging/subhurd]]).  This avoids deadlock, e.g.,
 when the instance of gdb stops the server but requires its use.  (Note: it is
-possible to use [[noninvasive_debugging|noninvasivedebugging]], but this is
-less flexible.)
+possible to use [[debugging/gdb/noninvasive_debugging]], but this is less
+flexible.)
 
 
 # Howto