From patchwork Fri Jul 27 05:02:34 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sergio Durigan Junior X-Patchwork-Id: 28643 Received: (qmail 81097 invoked by alias); 27 Jul 2018 05:02:42 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 81087 invoked by uid 89); 27 Jul 2018 05:02:41 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-25.6 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, SPF_HELO_PASS autolearn=ham version=3.3.2 spammy=Hx-languages-length:4612, imho, IMHO, composed X-HELO: mx1.redhat.com Received: from mx3-rdu2.redhat.com (HELO mx1.redhat.com) (66.187.233.73) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Fri, 27 Jul 2018 05:02:40 +0000 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id C2FA48011454; Fri, 27 Jul 2018 05:02:38 +0000 (UTC) Received: from psique.yyz.redhat.com (unused-10-15-17-196.yyz.redhat.com [10.15.17.196]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6CB7D2166BA3; Fri, 27 Jul 2018 05:02:38 +0000 (UTC) From: Sergio Durigan Junior To: GDB Patches Cc: Eli Zaretskii , Sergio Durigan Junior Subject: [PATCH] Improve gcore manpage and clarify "-o" option Date: Fri, 27 Jul 2018 01:02:34 -0400 Message-Id: <20180727050234.20742-1-sergiodj@redhat.com> X-IsSubscribed: yes 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 * 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 * 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(-) 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@"