Improve gcore manpage and clarify "-o" option

Ref.: https://bugs.debian.org/904628

It has been reported that gcore's manpage is a bit imprecise when it
comes to two things:

- It doesn't explicity say that the command accepts more than one PID
  on its CLI.

- It fails to mention that the argument passed through the "-o" option
  is actually a prefix that will be used to compose the corefile's
  filename, and not the actual filename.

I decided to give it a try and rewrite parts of the text to further
clarify these two points.  I ended up rewording the "Description"
section because, IMHO, it was a bit confuse to understand.

To make things consistent, I've also renamed the "$name" variable in
the gcore.in script, and expanded the usage text.

gdb/doc/ChangeLog:
2018-07-27  Sergio Durigan Junior  <sergiodj@redhat.com>

	* gdb.texinfo (gcore man): Rewrite "Description" and "-o"
	option sections to further clarify that gcore can take more
	than one PID, and that "-o" is used to specify a prefix, not a
	filename.

gdb/ChangeLog:
2018-07-27  Sergio Durigan Junior  <sergiodj@redhat.com>

	* gcore.in: Rename variable "name" to "prefix".  Expand
	"usage" text.

1 files changed, 7 insertions, 7 deletions

diff --git a/gdb/gcore.in b/gdb/gcore.in
index 233c00d..6fb307a 100644
--- a/gdb/gcore.in
+++ b/gdb/gcore.in
@@ -21,7 +21,7 @@
 #
 
 # Need to check for -o option, but set default basename to "core".
-name=core
+prefix=core
 
 # When the -a option is present, this may hold additional commands
 # to ensure gdb dumps all mappings (OS dependent).
@@ -38,10 +38,10 @@ while getopts :ao: opt; do
             esac
             ;;
         o)
-            name=$OPTARG
+            prefix=$OPTARG
             ;;
         *)
-            echo "usage:  @GCORE_TRANSFORM_NAME@ [-a] [-o filename] pid"
+            echo "usage:  @GCORE_TRANSFORM_NAME@ [-a] [-o prefix] pid1 [pid2...pidN]"
             exit 2
             ;;
     esac
@@ -51,7 +51,7 @@ shift $((OPTIND-1))
 
 if [ "$#" -eq "0" ]
 then
-    echo "usage:  @GCORE_TRANSFORM_NAME@ [-a] [-o filename] pid"
+    echo "usage:  @GCORE_TRANSFORM_NAME@ [-a] [-o prefix] pid1 [pid2...pidN]"
     exit 2
 fi
 
@@ -100,12 +100,12 @@ do
 	"$binary_path/@GDB_TRANSFORM_NAME@" </dev/null --nx --batch \
 	    -ex "set pagination off" -ex "set height 0" -ex "set width 0" \
 	    "${dump_all_cmds[@]}" \
-	    -ex "attach $pid" -ex "gcore $name.$pid" -ex detach -ex quit
+	    -ex "attach $pid" -ex "gcore $prefix.$pid" -ex detach -ex quit
 
-	if [ -r "$name.$pid" ] ; then
+	if [ -r "$prefix.$pid" ] ; then
 	    rc=0
 	else
-	    echo "@GCORE_TRANSFORM_NAME@: failed to create $name.$pid"
+	    echo "@GCORE_TRANSFORM_NAME@: failed to create $prefix.$pid"
 	    rc=1
 	    break
 	fi