From patchwork Sat Oct 13 17:58:00 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Darrington X-Patchwork-Id: 29729 Received: (qmail 106053 invoked by alias); 13 Oct 2018 17:58:09 -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 106024 invoked by uid 89); 13 Oct 2018 17:58:09 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-25.1 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, SPF_PASS autolearn=ham version=3.3.2 spammy=pipe, Program, listen, @value X-HELO: jocasta.intra Received: from de.cellform.com (HELO jocasta.intra) (88.217.224.109) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sat, 13 Oct 2018 17:58:07 +0000 Received: from jocasta.intra (localhost [127.0.0.1]) by jocasta.intra (8.15.2/8.15.2/Debian-8) with ESMTPS id w9DHw4H9002731 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Sat, 13 Oct 2018 19:58:04 +0200 Received: (from john@localhost) by jocasta.intra (8.15.2/8.15.2/Submit) id w9DHw4nW002727; Sat, 13 Oct 2018 19:58:04 +0200 From: John Darrington To: gdb-patches@sourceware.org Cc: John Darrington Subject: [PATCH 3/4] GDB: Fix documentation for invoking GDBSERVER Date: Sat, 13 Oct 2018 19:58:00 +0200 Message-Id: <20181013175801.2670-3-john@darrington.wattle.id.au> In-Reply-To: <20181013175801.2670-1-john@darrington.wattle.id.au> References: <20181013175801.2670-1-john@darrington.wattle.id.au> The documentation did not mention the possibility of invoking gdbserver with the new connection forms such as tcp6:host:port. This change fixes that. gdb/doc/ * gdb.texinfo (Server): Tabulate the various permitted forms of the @var{comm} metasyntactical variable. Include the unix:@var{host}:@var{socket} form as one of them. --- gdb/doc/gdb.texinfo | 60 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 44 insertions(+), 16 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 1e97d692b6..e3b62221cf 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -21097,9 +21097,19 @@ syntax is: target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] @end smallexample -@var{comm} is either a device name (to use a serial line), or a TCP -hostname and portnumber, or @code{-} or @code{stdio} to use -stdin/stdout of @code{gdbserver}. +@code{gdbserver} waits passively for the host @value{GDBN} to communicate +with it. + +@var{comm} may take several forms: + +@table @code +@item @code{@var{device}} +A serial line device. + +@item @code{-} +@itemx @code{stdio} +To use the stdin/stdout of @code{gdbserver}. + For example, to debug Emacs with the argument @samp{foo.txt} and communicate with @value{GDBN} over the serial port @file{/dev/com1}: @@ -21108,8 +21118,27 @@ For example, to debug Emacs with the argument target> gdbserver /dev/com1 emacs foo.txt @end smallexample -@code{gdbserver} waits passively for the host @value{GDBN} to communicate -with it. +The @code{stdio} connection is useful when starting @code{gdbserver} +with ssh: + +@smallexample +(gdb) target remote | ssh -T hostname gdbserver - hello +@end smallexample + +The @samp{-T} option to ssh is provided because we don't need a remote pty, +and we don't want escape-character handling. Ssh does this by default when +a command is provided, the flag is provided to make it explicit. +You could elide it if you want to. + +Programs started with stdio-connected gdbserver have @file{/dev/null} for +@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for +display through a pipe connected to gdbserver. +Both @code{stdout} and @code{stderr} use the same pipe. + +@item @code{@var{host}:@var{port}} +@itemx @code{tcp:@var{host}:@var{port}} +@itemx @code{tcp4:@var{host}:@var{port}} +To use a @acronym{TCP} @acronym{IPv4} socket connection on port number @var{port}. To use a TCP connection instead of a serial line: @@ -21129,22 +21158,21 @@ conflicts with another service, @code{gdbserver} prints an error message and exits.} You must use the same port number with the host @value{GDBN} @code{target remote} command. -The @code{stdio} connection is useful when starting @code{gdbserver} -with ssh: + +@item @code{tcp6:@var{host}:@var{port}} +To use a @acronym{TCP} @acronym{IPv6} socket connection on port number @var{port}. + +@item @code{unix:@var{host}:@var{local-socket}} +To use a Unix domain socket. This will create a socket with the file +system entry @var{local-socket} and listen on that. For example: @smallexample -(gdb) target remote | ssh -T hostname gdbserver - hello +target> gdbserver unix:localhost:/tmp/gdb-socket0 emacs foo.txt @end smallexample -The @samp{-T} option to ssh is provided because we don't need a remote pty, -and we don't want escape-character handling. Ssh does this by default when -a command is provided, the flag is provided to make it explicit. -You could elide it if you want to. +@var{host} must either be the null string or the literal string @code{localhost}. +@end table -Programs started with stdio-connected gdbserver have @file{/dev/null} for -@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for -display through a pipe connected to gdbserver. -Both @code{stdout} and @code{stderr} use the same pipe. @anchor{Attaching to a program} @subsubsection Attaching to a Running Program