On Sat May 17, 2025 at 05:55:06PM +0200, Ingo Schwarze wrote:
> 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
> 

I think Ingo, this is a huge improvement for new btrace users like me.

OK rsadowski

> 
> 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);
>  }
>  
>