linux.git/tools/lib/subcmd/parse-options.c, branch v7.2-rc1

tools subcmd: allow parsing distinct --opt and --no-opt

2026-05-28T11:02:48+00:00

libsubcmd automatically generates for every option --opt an equivalent
negated option, --no-opt, to unset the option. Vice versa, for every
option declared as --no-opt, a shorthand --opt is declared for
convenience.

Add a flag, PARSE_OPT_NOAUTONEG, to disable this behavior. This new flag
behaves similarly to the already existing PARSE_OPT_NONEG, only it does
not reject the --no-opt variant, but leaves it undefined. That is useful
when there is a conflicting distinct --no-opt option in the syntax of
the tool.

PARSE_OPT_NOAUTONEG is enabled per-option, allowing to unset other
options that do not have this conflict.

Link: https://lore.kernel.org/r/20260528103254.2990068-4-tglozar@redhat.com
Signed-off-by: Tomas Glozar

tools subcmd: support optarg as separate argument

2026-05-28T11:02:47+00:00

In addition to "-ovalue" and "--opt=value" syntax, allow also "-o value"
and "--opt value" for options with optional argument when the newly
added PARSE_OPT_OPTARG_ALLOW_NEXT flag is set.

This behavior is turned off by default since it does not make sense for
tools using non-option command line arguments. Consider the ambiguity
of "cmd -d x", where "-d x" can mean either "-d with argument of x" or
"-d without argument, followed by non-option argument x". This is not an
issue in the case that the tool takes no non-option arguments.

To implement this, a new local variable, force_defval, is created in
get_value(), along with a comment explaining the logic.

Link: https://lore.kernel.org/r/20260528103254.2990068-3-tglozar@redhat.com
Signed-off-by: Tomas Glozar

libsubcmd: Silence compiler warning

2024-10-23T21:38:34+00:00

Initialize the pointer 'o' in options__order to NULL to prevent a
compiler warning/error which is observed when compiling with the '-Og'
option, but is not emitted by the compiler with the current default
compilation options.

For example, when compiling libsubcmd with

 $ make "EXTRA_CFLAGS=-Og" -C tools/lib/subcmd/ clean all

Clang version 17.0.6 and GCC 13.3.1 fail to compile parse-options.c due
to following error:

  parse-options.c: In function ‘options__order’:
  parse-options.c:832:9: error: ‘o’ may be used uninitialized [-Werror=maybe-uninitialized]
    832 |         memcpy(&ordered[nr_opts], o, sizeof(*o));
        |         ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  parse-options.c:810:30: note: ‘o’ was declared here
    810 |         const struct option *o, *p = opts;
        |                              ^
  cc1: all warnings being treated as errors

Signed-off-by: Eder Zulian 
Signed-off-by: Andrii Nakryiko 
Acked-by: Arnaldo Carvalho de Melo 
Acked-by: Jiri Olsa 
Link: https://lore.kernel.org/bpf/20241022172329.3871958-4-ezulian@redhat.com

libsubcmd: Don't free the usage string

2024-09-04T12:54:24+00:00

Currently, commands which depend on 'parse_options_subcommand()' don't
show the usage string, and instead show '(null)'

    $ ./perf sched
	Usage: (null)

    -D, --dump-raw-trace  dump raw trace in ASCII
    -f, --force           don't complain, do it
    -i, --input     input file name
    -v, --verbose         be more verbose (show symbol address, etc)

'parse_options_subcommand()' is generally expected to initialise the usage
string, with information in the passed 'subcommands[]' array

This behaviour was changed in:

  230a7a71f92212e7 ("libsubcmd: Fix parse-options memory leak")

Where the generated usage string is deallocated, and usage[0] string is
reassigned as NULL.

As discussed in [1], free the allocated usage string in the main
function itself, and don't reset usage string to NULL in
parse_options_subcommand

With this change, the behaviour is restored.

    $ ./perf sched
        Usage: perf sched [] {record|latency|map|replay|script|timehist}

           -D, --dump-raw-trace  dump raw trace in ASCII
           -f, --force           don't complain, do it
           -i, --input     input file name
           -v, --verbose         be more verbose (show symbol address, etc)

[1]: https://lore.kernel.org/linux-perf-users/htq5vhx6piet4nuq2mmhk7fs2bhfykv52dbppwxmo3s7du2odf@styd27tioc6e/

Fixes: 230a7a71f92212e7 ("libsubcmd: Fix parse-options memory leak")
Suggested-by: Namhyung Kim 
Signed-off-by: Aditya Gupta 
Acked-by: Namhyung Kim 
Tested-by: Arnaldo Carvalho de Melo 
Cc: Athira Rajeev 
Cc: Disha Goel 
Cc: Ian Rogers 
Cc: Jiri Olsa 
Cc: Kajol Jain 
Cc: Madhavan Srinivasan 
Cc: Namhyung Kim 
Link: https://lore.kernel.org/r/20240904061836.55873-2-adityag@linux.ibm.com
Signed-off-by: Arnaldo Carvalho de Melo

tools lib subcmd: Show parent options in help

2024-05-13T00:09:52+00:00

I've just realized that help message in a subcommand didn't show one
in the parent command.  Since the option parser understands the parent,
display code should do the same.  For example, `perf ftrace latency -h`
should show options in the `perf ftrace` command too.

Before:

  $ perf ftrace latency -h

   Usage: perf ftrace [] []
      or: perf ftrace [] -- [] []
      or: perf ftrace {trace|latency} [] []
      or: perf ftrace {trace|latency} [] -- [] []

      -b, --use-bpf         Use BPF to measure function latency
      -n, --use-nsec        Use nano-second histogram
      -T, --trace-funcs 
                            Show latency of given function

After:

  $ perf ftrace latency -h

   Usage: perf ftrace [] []
      or: perf ftrace [] -- [] []
      or: perf ftrace {trace|latency} [] []
      or: perf ftrace {trace|latency} [] -- [] []

      -a, --all-cpus        System-wide collection from all CPUs
      -b, --use-bpf         Use BPF to measure function latency
      -C, --cpu        List of cpus to monitor
      -n, --use-nsec        Use nano-second histogram
      -p, --pid        Trace on existing process id
      -T, --trace-funcs 
                            Show latency of given function
      -v, --verbose         Be more verbose
          --tid        Trace on existing thread id (exclusive to --pid)

Reviewed-by: Ian Rogers 
Signed-off-by: Namhyung Kim 
Cc: Adrian Hunter 
Cc: Ingo Molnar 
Cc: Jiri Olsa 
Cc: Kan Liang 
Cc: Peter Zijlstra 
Link: https://lore.kernel.org/r/20240429233707.1511175-1-namhyung@kernel.org
Signed-off-by: Arnaldo Carvalho de Melo

libsubcmd: Fix parse-options memory leak

2024-05-10T14:16:48+00:00

If a usage string is built in parse_options_subcommand, also free it.

Fixes: 901421a5bdf605d2 ("perf tools: Remove subcmd dependencies on strbuf")
Signed-off-by: Ian Rogers 
Cc: Adrian Hunter 
Cc: Alexander Shishkin 
Cc: Ingo Molnar 
Cc: Jiri Olsa 
Cc: Josh Poimboeuf 
Cc: Kan Liang 
Cc: Mark Rutland 
Cc: Namhyung Kim 
Cc: Peter Zijlstra 
Link: https://lore.kernel.org/r/20240509052015.1914670-1-irogers@google.com
Signed-off-by: Arnaldo Carvalho de Melo

libsubcmd: Fix OPTION_GROUP sorting

2022-04-22T10:32:01+00:00

The OPTION_GROUP option type is a way of grouping certain options
together in the printed usage text.  It happens to be completely broken,
thanks to the fact that the subcmd option sorting just sorts everything,
without regard for grouping.  Luckily, nobody uses this option anyway,
though that will change shortly.

Fix it by sorting each group individually.

Signed-off-by: Josh Poimboeuf 
Signed-off-by: Peter Zijlstra (Intel) 
Reviewed-by: Miroslav Benes 
Link: https://lkml.kernel.org/r/e167ea3a11e2a9800eb062c1fd0f13e9cd05140c.1650300597.git.jpoimboe@redhat.com

libsubcmd: Fix OPT_CALLBACK_SET()

2020-07-17T12:33:06+00:00

Any option macro with _SET suffix should set opt->set variable which is
not happening for OPT_CALLBACK_SET(). This is causing issues with perf
record --switch-output-event. Fix that.

Before:

  # ./perf record --overwrite -e sched:*switch,syscalls:sys_enter_mmap \
           --switch-output-event syscalls:sys_enter_mmap
  ^C[ perf record: Woken up 1 times to write data ]
  [ perf record: Captured and wrote 0.297 MB perf.data (657 samples) ]

After:

  $ ./perf record --overwrite -e sched:*switch,syscalls:sys_enter_mmap \
          --switch-output-event syscalls:sys_enter_mmap
  [ perf record: dump data: Woken up 1 times ]
  [ perf record: Dump perf.data.2020061918144542 ]
  [ perf record: dump data: Woken up 1 times ]
  [ perf record: Dump perf.data.2020061918144608 ]
  [ perf record: dump data: Woken up 1 times ]
  [ perf record: Dump perf.data.2020061918144660 ]
  ^C[ perf record: dump data: Woken up 1 times ]
  [ perf record: Dump perf.data.2020061918144784 ]
  [ perf record: Woken up 0 times to write data ]
  [ perf record: Dump perf.data.2020061918144803 ]
  [ perf record: Captured and wrote 0.419 MB perf.data. ]

Fixes: 636eb4d001b1 ("libsubcmd: Introduce OPT_CALLBACK_SET()")
Signed-off-by: Ravi Bangoria 
Tested-by: Arnaldo Carvalho de Melo 
Cc: Jiri Olsa 
Link: http://lore.kernel.org/lkml/20200619133412.50705-1-ravi.bangoria@linux.ibm.com
Signed-off-by: Arnaldo Carvalho de Melo

tools lib subcmd: Introduce OPTION_ULONG

2018-10-19T14:56:58+00:00

For completeness, will be used in 'perf trace --max-events'.

Cc: Adrian Hunter 
Cc: Andi Kleen 
Cc: David Ahern 
Cc: Jiri Olsa 
Cc: Josh Poimboeuf 
Cc: Kim Phillips 
Cc: Namhyung Kim 
Cc: Wang Nan 
Link: https://lkml.kernel.org/n/tip-glaj3pwespxfj2fdjs9a20b6@git.kernel.org
Signed-off-by: Arnaldo Carvalho de Melo

perf tools: Add '\n' at the end of parse-options error messages

2018-04-18T18:35:51+00:00

Few error messages does not have '\n' at the end and thus next prompt
gets printed in the same line. Ex,

  linux~$ perf buildid-cache -verbose --add ./a.out
   Error: did you mean `--verbose` (with two dashes ?)linux~$

Fix it.

Signed-off-by: Ravi Bangoria 
Reviewed-by: Masami Hiramatsu 
Cc: Alexander Shishkin 
Cc: Jiri Olsa 
Cc: Kate Stewart 
Cc: Krister Johansen 
Cc: Namhyung Kim 
Cc: Peter Zijlstra 
Cc: Philippe Ombredanne 
Cc: Sihyeon Jang 
Cc: Thomas Gleixner 
Link: http://lkml.kernel.org/r/20180417041346.5617-2-ravi.bangoria@linux.vnet.ibm.com
Signed-off-by: Arnaldo Carvalho de Melo