gcore: add -h|--help options, and improve help/usage message output

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.

Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=32325
Approved-By: Tom Tromey <tom@tromey.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>

3 files changed, 52 insertions, 7 deletions

diff --git a/gdb/NEWS b/gdb/NEWS
index 0a1fadd..fae24d0 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 ef77657..dae3ef2 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -51391,7 +51391,7 @@ Richard M. Stallman and Roland H. Pesch, July 1991.
 
 @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
@@ -51425,6 +51425,10 @@ If not specified, @var{prefix} defaults to @var{gcore}.
 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 ce2f732..129e369 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