From patchwork Tue Feb 28 16:42:06 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Burgess X-Patchwork-Id: 65780 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 1D315385084A for ; Tue, 28 Feb 2023 16:43:11 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 1D315385084A DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1677602591; bh=N+mpucfYCs/G7yQyTFmFsSLUFGWqA/amoytyGoQADsY=; h=To:Cc:Subject:Date:In-Reply-To:References:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From:Reply-To:From; b=VcACVQOflJPyiJZjn6sLqs56HF9nQQEkj8Y7GFZrlF8DtsK7Y17ndt9ewvFnHy8Xy 2InNglwOUzqp+zJm2bTxBh+IDG6/0x8EvGMqc1r6DAEdOhbsSODPtOXAkxsGli7y1g QyR+Ty+2gJPvFNBHgGY6wF34O7gfPp44ORx2dVjI= X-Original-To: gdb-patches@sourceware.org Delivered-To: gdb-patches@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 02ABA3858D33 for ; Tue, 28 Feb 2023 16:42:24 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 02ABA3858D33 Received: from mail-ed1-f72.google.com (mail-ed1-f72.google.com [209.85.208.72]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_128_GCM_SHA256) id us-mta-55-uhA3nTqZMXe6wNr4IOtinQ-1; Tue, 28 Feb 2023 11:42:23 -0500 X-MC-Unique: uhA3nTqZMXe6wNr4IOtinQ-1 Received: by mail-ed1-f72.google.com with SMTP id r6-20020aa7c146000000b004acd97105ffso14740776edp.19 for ; Tue, 28 Feb 2023 08:42:23 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1677602542; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=N+mpucfYCs/G7yQyTFmFsSLUFGWqA/amoytyGoQADsY=; b=lik6wC9mdtZfkhgKE8sv5o1Vku0ChZg653w8hlrgcVhrHwtemN9HGZDVvlwjAkUVgb h7V1FypBez5+P2bRqyrME25lCEgBSWB4G7zQaula3kscNviuRvP82LAw/xVN2SjlXDvq KwbH1JoZa3mXQux+hQBF1CdsAfqRX17A+uOWwd4GFcK2Rotll+BJF62B8ZTLs+g7nTPv UETIw5FXm78gqTCwYeS3c/FB/5YvWGd6gQ4mpbKVe8Gx1U4YbXCUBy064h/4enV3T7iT e/aymLGaObOjoWOt+OUZpTvoW9CdiieV/zBwvptRdD3ymSTc/WjdP54UoH93JWTGzh5Z 7gOQ== X-Gm-Message-State: AO0yUKUzNGcYy03rkHxaGZ0pgRE1x1DtXL7sxxL0ydyyxQIA2SPnp/4t fMNxUFoM8NA/HQ7LOF7QQP2i3jfU2b6fErT3Vag+4VGV0O3zCtJiEQusd9uHDgpaczXL2Vo1luu 1wvLobO/CQtr7n3yWyxJPPKEDNdqvue5haiaD9F/nZh3b7eaze0yZ4zm5+4KjzdlY2xO3oEsvmk dXJgA= X-Received: by 2002:aa7:c511:0:b0:4af:5000:ab19 with SMTP id o17-20020aa7c511000000b004af5000ab19mr3781688edq.18.1677602542065; Tue, 28 Feb 2023 08:42:22 -0800 (PST) X-Google-Smtp-Source: AK7set9AcLkv40GcDuwTONXt2Z7bQrTNwapE3THS3YvanvbCZl4GsZM5r7iTJFqZfm/ScR27eXehYA== X-Received: by 2002:aa7:c511:0:b0:4af:5000:ab19 with SMTP id o17-20020aa7c511000000b004af5000ab19mr3781670edq.18.1677602541677; Tue, 28 Feb 2023 08:42:21 -0800 (PST) Received: from localhost (95.72.115.87.dyn.plus.net. [87.115.72.95]) by smtp.gmail.com with ESMTPSA id m3-20020a50d7c3000000b004accf3a63cbsm4531722edj.68.2023.02.28.08.42.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 28 Feb 2023 08:42:21 -0800 (PST) To: gdb-patches@sourceware.org Cc: Andrew Burgess Subject: [PATCHv4 01/12] gdb/doc: extended documentation for inferior function calls Date: Tue, 28 Feb 2023 16:42:06 +0000 Message-Id: X-Mailer: git-send-email 2.25.4 In-Reply-To: References: MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-11.7 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_NONE, TXREP, WEIRD_PORT autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Andrew Burgess via Gdb-patches From: Andrew Burgess Reply-To: Andrew Burgess Errors-To: gdb-patches-bounces+patchwork=sourceware.org@sourceware.org Sender: "Gdb-patches" Eli already approved these docs changes: https://sourceware.org/pipermail/gdb-patches/2023-January/195869.html --- I noticed that the documentation for inferior function calls doesn't say much about what happens if/when an inferior function call is interrupted, i.e. it doesn't describe what the dummy frame looks like on the stack, or how GDB behaves when the inferior is continued and reaches the dummy frame. This commit aims to add some of this missing information. --- gdb/doc/gdb.texinfo | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index c1ca45521ea..1170a2dacc3 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -20779,6 +20779,7 @@ in that case is controlled by the @code{set unwind-on-terminating-exception} command. +@anchor{stack unwind settings} @table @code @item set unwindonsignal @kindex set unwindonsignal @@ -20836,6 +20837,37 @@ @end table +When calling a function within a program, it is possible that the +program could enter a state from which the called function may never +return. If this happens then it is possible to interrupt the function +call by typing the interrupt character (often @kbd{Ctrl-c}). + +If a called function is interrupted for any reason, including hitting +a breakpoint, or triggering a watchpoint, and the stack is not unwound +due to @code{set unwind-on-terminating-exception on} or @code{set +unwindonsignal on} (@pxref{stack unwind settings}), +then the dummy-frame, created by @value{GDBN} to facilitate the call +to the program function, will be visible in the backtrace, for example +frame @code{#3} in the following backtrace: + +@smallexample +(@value{GDBP}) backtrace +#0 0x00007ffff7b3d1e7 in nanosleep () from /lib64/libc.so.6 +#1 0x00007ffff7b3d11e in sleep () from /lib64/libc.so.6 +#2 0x000000000040113f in deadlock () at test.cc:13 +#3 +#4 breakpt () at test.cc:20 +#5 0x0000000000401151 in main () at test.cc:25 +@end smallexample + +At this point it is possible to examine the state of the inferior just +like any other stop. + +Depending on why the function was interrupted then it may be possible +to resume the inferior (using commands like @code{continue}, +@code{step}, etc). In this case, when the inferior finally returns to +the dummy-frame, @value{GDBN} will once again halt the inferior. + @subsection Calling functions with no debug info @cindex no debug info functions