[PATCH 2/3] gcore: add -h|--help options, and improve help/usage message output

[Andrew Burgess <aburgess@redhat.com>]

Like the previous commit, this copies a lot from:

  commit fb2ded33c1e519659743047ed7817166545b6d91
  Date:   Fri Dec 20 12:46:11 2024 -0800

      Add gstack script

And adds -h | --help options to the gcore script, and smartens up the
help and usage output messages.

The usage text is now split over several lines (as it was getting a
bit long), and an input error suggests using `--help` instead of
printing the full usage string.

These changes bring gcore and gstack closer in behaviour.
---
 gdb/NEWS            |  3 ++-
 gdb/doc/gdb.texinfo |  6 +++++-
 gdb/gcore-1.in      | 50 ++++++++++++++++++++++++++++++++++++++++-----
 3 files changed, 52 insertions(+), 7 deletions(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index d4453914755..5d9d9fb3063 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -27,7 +27,8 @@
 * Linux checkpoint code has been updated to work with multiple inferiors.
 
 * The gcore script now has a -v or --version option, which prints the
-  version number, and then exits.
+  version number, and then exits.  As well as a -h or --help option,
+  which prints each options and a brief description.
 
 * New commands
 
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 1ab87dd37f9..a1ae45c5121 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -51386,7 +51386,7 @@ gcore man
 
 @format
 @c man begin SYNOPSIS gcore
-gcore [-v | --version] [-a] [-o @var{prefix}] [-d @var{directory}]
+gcore [-v | --version] [-h | --help] [-a] [-o @var{prefix}] [-d @var{directory}]
       @var{pid1} [@var{pid2}...@var{pidN}]
 @c man end
 @end format
@@ -51420,6 +51420,10 @@ gcore man
 Use @var{directory} as the data directory when invoking @value{GDBN} for running
 the gcore command. This argument is optional.
 
+@item --help
+@itemx -h
+List all options, with brief explanations.
+
 @item --version
 @itemx -v
 Print version information and then exit.
diff --git a/gdb/gcore-1.in b/gdb/gcore-1.in
index ce2f7321148..129e3697fb7 100644
--- a/gdb/gcore-1.in
+++ b/gdb/gcore-1.in
@@ -32,11 +32,38 @@ dump_all_cmds=()
 
 data_directory_opt=()
 
+function print_usage() {
+    prefix="Usage: $0"
+    paddin=$(printf '%*s' ${#prefix})
+
+    echo "$prefix [-h|--help] [-v|--version]"
+    echo "$paddin [-a] [-o prefix] [-d data-directory]"
+    echo "$paddin pid1 [pid2...pidN]"
+}
+
+function print_try_help() {
+    echo "Try '$0 --help' for more information."
+}
+
+function print_help() {
+    print_usage
+    echo
+    echo "Create a core file of a running program using GDB."
+    echo
+    echo "  -h, --help         Print this message then exit."
+    echo "  -v, --version      Print version information then exit."
+    echo "  -a                 Dump all memory mappings."
+    echo "  -o prefix          Use 'prefix.pid' as the core file name."
+    echo "                       The default prefix is 'core'."
+    echo "  -d dir             Pass '--data-directory dir' as an argument"
+    echo "                       to GDB."
+}
+
 function print_version() {
     echo "GNU gcore (${PKGVERSION}) ${VERSION}"
 }
 
-while getopts :vao:d:-: OPT; do
+while getopts vhao:d:-: OPT; do
     if [ "$OPT" = "-" ]; then
 	OPT="${OPTARG%%=*}"
 	OPTARG="${OPTARG#'$OPT'}"
@@ -58,13 +85,26 @@ while getopts :vao:d:-: OPT; do
         d)
             data_directory_opt=("--data-directory" "$OPTARG")
             ;;
+	h | help)
+	    print_help
+	    exit 0
+	    ;;
 	v | version)
 	    print_version
 	    exit 0
 	    ;;
+	\?)
+	    # getopts has already output an error message.
+	    print_try_help 1>&2
+	    exit 2
+	    ;;
         *)
-            echo "usage:  @GCORE_TRANSFORM_NAME@ [-v | --version] [-a] [-o prefix] [-d data-directory] pid1 [pid2...pidN]"
-            exit 2
+	    # Unknown single character options are handled by the \?
+	    # case above.  This is formatted to match the error
+	    # getopts gives for an unknown single character option.
+	    echo "$0: illegal option -- $OPT" 1>&2
+	    print_try_help 1>&2
+	    exit 2
             ;;
     esac
 done
@@ -73,8 +113,8 @@ shift $((OPTIND-1))
 
 if [ "$#" -eq "0" ]
 then
-    echo "usage:  @GCORE_TRANSFORM_NAME@ [-a] [-o prefix] [-d data-directory] pid1 [pid2...pidN]"
-    exit 2
+    print_usage 1>&2
+    exit 1
 fi
 
 # Attempt to fetch the absolute path to the gcore script that was
-- 
2.47.1