From: Ingo Schwarze <schwarze@usta.de>
Subject: Re: btrace(1): fix -e and filename args
To: Claudio Jeker <cjeker@diehard.n-r-g.com>, Rafael Sadowski <rafael@sizeofvoid.org>
Cc: tech@openbsd.org, jmc@openbsd.org
Date: Sat, 17 May 2025 17:55:06 +0200

Hello Claudio, Rafael, Jason,

Claudio Jeker wrote on Sat, May 17, 2025 at 02:00:30PM +0200:

> If no -e is used then btrace will use the first argument as filename to a
> bt(5) script and all other arguments are passed to the btrace script as
> $1, $2, etc.

Oh, like ksh(1) [-c string | -s | file [argument ...]],
except that either a program file or -e is mandatory and reading
from standard input is not supported.

In that case, i propose the diff below.

Rationale:
 * ".Op Fl e Ar program | Ar file" is wrong because providing a
   program is not optional.
 * The same is also confusing because it is ambiguous whether it means
   (-e program) | file   or   -e (program | file).
   That can be fixed by switching the order.
 * .Ar file must not precede .Fl p.
 * Having two different option arguments for two different options
   both named file is bad.  Choose a descriptive name for each
   option argument.
 * The first sentence of the DESCRIPTION is supposed to describe the
   default behaviour, i.e. the behaviour when no options are present.
   No need to complicate it by discussing the -e option.
 * Right now, the .Ar arguments are not described at all, which
   confused multiple developers who tried to work on this diff.
   The proper place is in the first sentence.
 * Be less terse when documenting -e.  My proposal may seem
   slightly wordy, but given how much confusion the mildly
   unusual semantics has already caused in this thread,
   i believe being very explicit is worth the three lines of text.
 * Admittedly, my SYNOPSIS does not express whether or not
     btrace programfile argument ...
   is valid (the same ambiguity exosts in the ksh(1) SYNOPSIS).
   In Linux manpages, it is common to write something like
     [-lnv] [-p elffile] {programfile | -e program} [argument ...]
   for such cases but we don't usually do that.
   I think it isn't needed as long as the DESCRIPTION settles
   the question.

OK?
  Ingo


Index: btrace.8
===================================================================
RCS file: /cvs/src/usr.sbin/btrace/btrace.8,v
diff -u -r1.9 btrace.8
--- btrace.8	15 Sep 2023 10:56:46 -0000	1.9
+++ btrace.8	17 May 2025 15:30:53 -0000
@@ -23,8 +23,8 @@
 .Sh SYNOPSIS
 .Nm btrace
 .Op Fl lnv
-.Op Fl e Ar program | Ar file
-.Op Fl p Ar file
+.Op Fl p Ar elffile
+.Ar programfile | Fl e Ar program
 .Op Ar argument ...
 .Sh DESCRIPTION
 The
@@ -33,24 +33,32 @@
 programs.
 It interprets the
 .Xr bt 5
-program in
-.Ar file
-and communicates with the dynamic tracer device using the interface described in
+program read from the
+.Ar programfile ,
+passing the optional
+.Ar arguments
+to it, and communicates with the dynamic tracer device
+using the interface described in
 .Xr dt 4 .
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl e Ar program
-Execute
+Execute the
+.Ar program
+specified as the option argument instead of reading a program from a file.
+In this case, all non-option
+.Ar arguments
+are passed through to the
 .Ar program .
 .It Fl l
 List all available probes.
 .It Fl n
 No action.
 Parse the program and then exit.
-.It Fl p Ar file
-Load symbols from
-.Ar file
+.It Fl p Ar elffile
+Load symbols from the
+.Ar elffile
 to convert
 .Va ustack
 addresses into function names.
Index: btrace.c
===================================================================
RCS file: /cvs/src/usr.sbin/btrace/btrace.c,v
diff -u -r1.96 btrace.c
--- btrace.c	1 Mar 2025 12:40:33 -0000	1.96
+++ btrace.c	17 May 2025 15:30:53 -0000
@@ -231,8 +231,8 @@
 __dead void
 usage(void)
 {
-	fprintf(stderr, "usage: %s [-lnv] [-e program | file] [-p file] "
-	    "[argument ...]\n", getprogname());
+	fprintf(stderr, "usage: %s [-lnv] [-p elffile] "
+	    "programfile | -e program [argument ...]\n", getprogname());
 	exit(1);
 }