diff mbox

Improve gcore manpage and clarify "-o" option

Message ID 20180727050234.20742-1-sergiodj@redhat.com
State New, archived
Headers

Commit Message

Sergio Durigan Junior July 27, 2018, 5:02 a.m. UTC 
  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:
yyyy-mm-dd  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:
yyyy-mm-dd  Sergio Durigan Junior  <sergiodj@redhat.com>

	* gcore.in: Rename variable "name" to "prefix".  Expand
	"usage" text.
---
 gdb/doc/gdb.texinfo | 24 +++++++++++++-----------
 gdb/gcore.in        | 14 +++++++-------
 2 files changed, 20 insertions(+), 18 deletions(-)

Comments

Eli Zaretskii July 27, 2018, 6:08 a.m. UTC | #1 
> From: Sergio Durigan Junior <sergiodj@redhat.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,
> 	Sergio Durigan Junior <sergiodj@redhat.com>
> Date: Fri, 27 Jul 2018 01:02:34 -0400
> 
> 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:
> yyyy-mm-dd  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:
> yyyy-mm-dd  Sergio Durigan Junior  <sergiodj@redhat.com>
> 
> 	* gcore.in: Rename variable "name" to "prefix".  Expand
> 	"usage" text.

This is OK, thanks.
Sergio Durigan Junior July 27, 2018, 7:57 p.m. UTC | #2 
On Friday, July 27 2018, Eli Zaretskii wrote:

>> From: Sergio Durigan Junior <sergiodj@redhat.com>
>> Cc: Eli Zaretskii <eliz@gnu.org>,
>> 	Sergio Durigan Junior <sergiodj@redhat.com>
>> Date: Fri, 27 Jul 2018 01:02:34 -0400
>> 
>> 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:
>> yyyy-mm-dd  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:
>> yyyy-mm-dd  Sergio Durigan Junior  <sergiodj@redhat.com>
>> 
>> 	* gcore.in: Rename variable "name" to "prefix".  Expand
>> 	"usage" text.
>
> This is OK, thanks.

Thanks, pushed:

129eb0f1f16dc7a49799a024a7bcb109d954a1e7
diff mbox

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b95c2b4f49..71aef2293f 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -43765,16 +43765,17 @@  Richard M. Stallman and Roland H. Pesch, July 1991.
 
 @format
 @c man begin SYNOPSIS gcore
-gcore [-a] [-o @var{filename}] @var{pid}
+gcore [-a] [-o @var{prefix}] @var{pid1} [@var{pid2}...@var{pidN}]
 @c man end
 @end format
 
 @c man begin DESCRIPTION gcore
-Generate a core dump of a running program with process ID @var{pid}.
-Produced file is equivalent to a kernel produced core file as if the process
-crashed (and if @kbd{ulimit -c} were used to set up an appropriate core dump
-limit).  Unlike after a crash, after @command{gcore} the program remains
-running without any change.
+Generate core dumps of one or more running programs with process IDs
+@var{pid1}, @var{pid2}, etc.  A core file produced by @command{gcore}
+is equivalent to one produced by the kernel when the process crashes
+(and when @kbd{ulimit -c} was used to set up an appropriate core dump
+limit).  However, unlike after a crash, after @command{gcore} finishes
+its job the program remains running without any change.
 @c man end
 
 @c man begin OPTIONS gcore
@@ -43786,11 +43787,12 @@  the Operating System.  On @sc{gnu}/Linux, it will disable
 enable @code{dump-excluded-mappings} (@pxref{set
 dump-excluded-mappings}).
 
-@item -o @var{filename}
-The optional argument
-@var{filename} specifies the file name where to put the core dump.
-If not specified, the file name defaults to @file{core.@var{pid}},
-where @var{pid} is the running program process ID.
+@item -o @var{prefix}
+The optional argument @var{prefix} specifies the prefix to be used
+when composing the file names of the core dumps.  The file name is
+composed as @file{@var{prefix}.@var{pid}}, where @var{pid} is the
+process ID of the running program being analyzed by @command{gcore}.
+If not specified, @var{prefix} defaults to @var{gcore}.
 @end table
 @c man end
 
diff --git a/gdb/gcore.in b/gdb/gcore.in
index 233c00d366..6fb307a5dc 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