Describe "right" argumens in ltrace.conf.5. Add a related TODO item

2 files changed, 64 insertions, 0 deletions

diff --git a/TODO b/TODO
index 6a81530..a06c5f1 100644
--- a/TODO
+++ b/TODO
@@ -25,5 +25,34 @@
 ** Config file syntax
 *** typedef should be able to assign a lens to a name
 *** format should take arguments like string does
+** More fine-tuned control of right arguments
+   Combination of named arguments and some extensions could take care
+   of that:
+
+   | void func(X=hide(int*), long*, +pack(X)); |
+
+   This would show long* as input argument (i.e. the function could
+   mangle it), and later show the pre-fetched X.  The "pack" syntax is
+   utterly undeveloped as of now.  The general idea is to produce
+   arguments that expand to some mix of types and values.  But maybe
+   all we need is something like
+
+   | void func(out int*, long*); |
+
+   ltrace would know that out/inout/in arguments are given in the
+   right order, but left pass should display in and inout arguments
+   only, and right pass then out and inout.  + would be
+   backward-compatible syntactic sugar, expanded like so:
+
+   | void func(int*, int*, +long*, long*);              |
+   | void func(in int*, in int*, out long*, out long*); |
+
+   But sometimes we may want to see a different type on the way in and
+   on the way out.  E.g. in asprintf, what's interesting on the way in
+   is the address, but on the way out we want to see buffer contents.
+   Does something like the following make sense?
+
+   | void func(X=void*, long*, out string(X)); |
+
 * BUGS
 ** After a clone(), syscalls may be seen as sysrets in s390 (see trace.c:syscall_p())
diff --git a/ltrace.conf.5 b/ltrace.conf.5
index a766d53..6ede2ce 100644
--- a/ltrace.conf.5
+++ b/ltrace.conf.5
@@ -239,6 +239,41 @@ determine what the following actual arguments are.  E.g. if the format
 string is "%s %d\\n", it's as if the \fBformat\fR was replaced by
 \fBstring, string, int\fR.
 
+.SH RETURN ARGUMENTS
+
+C functions often use one or more arguments for returning values back
+to the caller.  The caller provides a pointer to storage, which the
+called function initializes.  Ltrace has some support for this idiom.
+
+When a traced binary hits a function call, ltrace first fetches all
+arguments.  It then displays \fIleft\fR portion of the argument list.
+Only when the function returns does ltrace display \fIright\fR portion
+as well.  Typically, left portion takes up all the arguments, and
+right portion only contains return value.  But ltrace allows you to
+configure where exactly to put the dividing line by means of a \fB+\fR
+operator placed in front of an argument:
+
+.RS
+.B int\fR asprintf\fB(+string*, format);
+.RE
+
+Here, the first argument to asprintf is denoted as return argument,
+which means that displaying the whole argument list is delayed until
+the function returns:
+
+.RS
+a.out->asprintf( <unfinished ...>
+.br
+libc.so.6->malloc(100)                   = 0x245b010
+.br
+[... more calls here ...]
+.br
+<... asprintf resumed> "X=1", "X=%d", 1) = 5
+.RE
+
+It is currently not possible to have an "inout" argument that passes
+information in both directions.
+
 .SH EXAMPLES
 
 In the following, the first is the C prototype, and following that is