[binutils-gdb] Improve gcore manpage and clarify "-o" option
Sergio Durigan Junior
sergiodj@sourceware.org
Fri Jul 27 19:57:00 GMT 2018
https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=129eb0f1f16dc7a49799a024a7bcb109d954a1e7
commit 129eb0f1f16dc7a49799a024a7bcb109d954a1e7
Author: Sergio Durigan Junior <sergiodj@redhat.com>
Date: Fri Jul 27 00:52:23 2018 -0400
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.
Diff:
---
gdb/ChangeLog | 5 +++++
gdb/doc/ChangeLog | 7 +++++++
gdb/doc/gdb.texinfo | 24 +++++++++++++-----------
gdb/gcore.in | 14 +++++++-------
4 files changed, 32 insertions(+), 18 deletions(-)
diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 8a63224..bee8bff 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,8 @@
+2018-07-27 Sergio Durigan Junior <sergiodj@redhat.com>
+
+ * gcore.in: Rename variable "name" to "prefix". Expand
+ "usage" text.
+
2018-07-14 Jon Turney <jon.turney@dronecode.org.uk>
* windows-nat.c (windows_nat_target::create_inferior): Update to
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 1bcf9df..90784b5 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,10 @@
+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.
+
2018-07-26 Andrew Burgess <andrew.burgess@embecosm.com>
* gdb.texinfo (Maintenance Commands): Add description of
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b95c2b4..71aef22 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 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
More information about the Gdb-cvs
mailing list