Re: rpctrace man page

2016-11-04 Thread Ludovic Courtès
Hello!

Thanks for taking care of the manual!  Just a very very partial review…

"Brent W. Baccala"  skribis:

> +@node rpctrace
> +@section rpctrace

The convention would be to call this section “Invoking rpctrace”, so:

  @node Invoking rpctrace
  @section Invoking @command{rpctrace}

> +@example
> +rpctrace [-E var[=value]] [-i FILE] [-I DIR] [--nostdinc] [-o FILE] [-s 
> SIZE] command [args]

Perhaps simply:

@example
rpctrace @var{options} @var{command} @var{args}...
@end example

> +@item -E @var{var[=value]}

@item -E @var{var}[=@var{value}]

My .2¢,
Ludo’.




Re: rpctrace man page

2016-11-02 Thread Brent W. Baccala
On Tue, Nov 1, 2016 at 5:15 AM, Samuel Thibault 
wrote:

>
> GNU projects usually don't have man pages, but info pages.  The
> doc/hurd.texi indeed doesn't have any part for rpctrace.  It should :)
>
>
What an embarrassing *faux pas*!  It's like fumbling to put the Metro card
in the turnstile, like asking the meaning of the local argot, like
mispronouncing Wahiawa...


> I also notice that "info settrans" doesn't seem to bring to the settrans
> part of the documentation.  That should be fixed.
>

 The attached patches should address both points.

agape
brent
From d89c1aee558a2b83270db908e923d9f3395adcb5 Mon Sep 17 00:00:00 2001
From: Brent Baccala 
Date: Tue, 1 Nov 2016 03:55:27 -1000
Subject: [PATCH 1/2] add rpctrace documentation to info file

---
 doc/hurd.texi | 147 ++
 1 file changed, 147 insertions(+)

diff --git a/doc/hurd.texi b/doc/hurd.texi
index 8428a77..06b5a61 100644
--- a/doc/hurd.texi
+++ b/doc/hurd.texi
@@ -162,6 +162,7 @@ into another language, under the above conditions for modified versions.
 * Networking::  Interconnecting with other machines.
 * Terminal Handling::   Helping people interact with the Hurd.
 * Running Programs::Program execution and process management.
+* Debugging Programs::  Tracing and debugging programs.
 * Authentication::  Verifying user and server privileges.
 * Index::   Guide to concepts, functions, and files.
 
@@ -319,6 +320,10 @@ Networking
 * libpipe::
 * Socket Interface::Network communication I/O protocol.
 
+Debugging Programs
+
+* rpctrace::Trace Mach Remote Procedure Calls
+
 Authentication
 
 * Auth Interface::  Auth ports implement the auth interface.
@@ -4647,6 +4652,148 @@ FIXME: finish
 @section proc
 @section crash
 
+@node Debugging Programs
+@chapter Debugging Programs
+
+@menu
+* rpctrace::Trace Mach Remote Procedure Calls
+@end menu
+
+@node rpctrace
+@section rpctrace
+@pindex rpctrace
+
+@command{rpctrace}
+runs a specified program until it exits, intercepting and tracing its Remote Procedure Calls.
+Child processes are also traced.  Synopsis:
+
+@example
+rpctrace [-E var[=value]] [-i FILE] [-I DIR] [--nostdinc] [-o FILE] [-s SIZE] command [args]
+@end example
+
+Each line in the trace begins with the port to which the RPC is being sent, followed
+by the name of the RPC, its arguments in parenthesis, an equal sign, and then the reply.
+
+Mach ports are identified using port numbers internal to @command{rpctrace}
+(not the program being traced),
+and are printed in the format
+@code{@var{DEST}<--@var{SRC}(@var{PID})},
+where @var{SRC} is the port number @command{rpctrace} received the message on,
+@var{DEST} is the port number it is forwarding the message to, and
+@var{PID} identifies which task the source port is associated with.
+Only traced processes are identified by PID; ports sourced from untraced processes
+(and the kernel) are tagged with PID -1.
+
+Consider the following line from @command{rpctrace}:
+
+@example
+110<--536(pid1290)->dir_lookup ("etc/ld.so.cache" 1 0) = 0 1 ""530<--540(pid1290)
+@end example
+
+Process 1290 has transmitted a @samp{dir_lookup} RPC, which was received by
+@command{rpctrace}
+on port 536 and forwarded to port 110, containing three arguments: a string and two integers.
+A reply message was received containing two integers, a null string, and a send right to
+a Mach port.  If process 1290 now transmits a message to its new send right, it will
+be received by @command{rpctrace} on port 540 and forwarded to port 530.
+
+Task ports and thread ports are recognized by @command{rpctrace}
+and printed in special formats:
+@code{@var{TASK}(@var{PID})} and @code{@var{THREAD}(@var{PID})}.
+Thus, the following line shows process 1290 making an RPC to its own task port
+(though this association is not obvious) and allocating a new receive right,
+which appears on port number 17 (in process 1290's port space, not
+@command{rpctrace}'s).
+
+@example
+task523(pid1290)->mach_port_allocate (1) = 0 pn@{ 17@}
+@end example
+
+If the message immediately following an RPC is not a reply to that RPC, a continuation
+line is printed, using a number that is the port @command{rpctrace}
+is expecting the reply on.  The following sequence shows process 1290 making two
+RPCs (probably from two different threads), and then the two replies being received:
+
+@example
+task523(pid1290)->vm_allocate (0 4096 1) ...525
+task523(pid1290)->task_set_special_port (3530<--544(pid-1)) ...543
+525... = 0 19619840
+543... = 0
+@end example
+
+Some RPCs (called @dfn{simpleroutines})
+have no reply message, and are printed with a terminating semicolon, i.e:
+
+@example
+68<--70(pid1731)->memory_object_lock_request (0 4096 2 0 8   98);
+@end example
+
+Port numbers for send-once rights are printed without any additional
+identifying informati

Re: rpctrace man page

2016-11-01 Thread Samuel Thibault
Hello,

Brent W. Baccala, on Mon 31 Oct 2016 21:00:53 -1000, wrote:
> How about writing a man page?

GNU projects usually don't have man pages, but info pages.  The
doc/hurd.texi indeed doesn't have any part for rpctrace.  It should :)

I also notice that "info settrans" doesn't seem to bring to the settrans
part of the documentation.  That should be fixed.

Samuel