doc/gdb/Calling.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs
Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Debugging with GDB: Calling</title>

<meta name="description" content="Debugging with GDB: Calling">
<meta name="keywords" content="Debugging with GDB: Calling">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Altering.html#Altering" rel="up" title="Altering">
<link href="Patching.html#Patching" rel="next" title="Patching">
<link href="Returning.html#Returning" rel="previous" title="Returning">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Calling"></a>
<div class="header">
<p>
Next: <a href="Patching.html#Patching" accesskey="n" rel="next">Patching</a>, Previous: <a href="Returning.html#Returning" accesskey="p" rel="previous">Returning</a>, Up: <a href="Altering.html#Altering" accesskey="u" rel="up">Altering</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Calling-Program-Functions"></a>
<h3 class="section">17.5 Calling Program Functions</h3>

<dl compact="compact">
<dd><a name="index-calling-functions"></a>
<a name="index-inferior-functions_002c-calling"></a>
</dd>
<dt><code>print <var>expr</var></code></dt>
<dd><p>Evaluate the expression <var>expr</var> and display the resulting value.
The expression may include calls to functions in the program being
debugged.
</p>
<a name="index-call"></a>
</dd>
<dt><code>call <var>expr</var></code></dt>
<dd><p>Evaluate the expression <var>expr</var> without displaying <code>void</code>
returned values.
</p>
<p>You can use this variant of the <code>print</code> command if you want to
execute a function from your program that does not return anything
(a.k.a. <em>a void function</em>), but without cluttering the output
with <code>void</code> returned values that <small>GDB</small> will otherwise
print.  If the result is not void, it is printed and saved in the
value history.
</p></dd>
</dl>

<p>It is possible for the function you call via the <code>print</code> or
<code>call</code> command to generate a signal (e.g., if there&rsquo;s a bug in
the function, or if you passed it incorrect arguments).  What happens
in that case is controlled by the <code>set unwindonsignal</code> command.
</p>
<p>Similarly, with a C<tt>++</tt> program it is possible for the function you
call via the <code>print</code> or <code>call</code> command to generate an
exception that is not handled due to the constraints of the dummy
frame.  In this case, any exception that is raised in the frame, but has
an out-of-frame exception handler will not be found.  GDB builds a
dummy-frame for the inferior function call, and the unwinder cannot
seek for exception handlers outside of this dummy-frame.  What happens
in that case is controlled by the
<code>set unwind-on-terminating-exception</code> command.
</p>
<dl compact="compact">
<dt><code>set unwindonsignal</code></dt>
<dd><a name="index-set-unwindonsignal"></a>
<a name="index-unwind-stack-in-called-functions"></a>
<a name="index-call-dummy-stack-unwinding"></a>
<p>Set unwinding of the stack if a signal is received while in a function
that <small>GDB</small> called in the program being debugged.  If set to on,
<small>GDB</small> unwinds the stack it created for the call and restores
the context to what it was before the call.  If set to off (the
default), <small>GDB</small> stops in the frame where the signal was
received.
</p>
</dd>
<dt><code>show unwindonsignal</code></dt>
<dd><a name="index-show-unwindonsignal"></a>
<p>Show the current setting of stack unwinding in the functions called by
<small>GDB</small>.
</p>
</dd>
<dt><code>set unwind-on-terminating-exception</code></dt>
<dd><a name="index-set-unwind_002don_002dterminating_002dexception"></a>
<a name="index-unwind-stack-in-called-functions-with-unhandled-exceptions"></a>
<a name="index-call-dummy-stack-unwinding-on-unhandled-exception_002e"></a>
<p>Set unwinding of the stack if a C<tt>++</tt> exception is raised, but left
unhandled while in a function that <small>GDB</small> called in the program being
debugged.  If set to on (the default), <small>GDB</small> unwinds the stack
it created for the call and restores the context to what it was before
the call.  If set to off, <small>GDB</small> the exception is delivered to
the default C<tt>++</tt> exception handler and the inferior terminated.
</p>
</dd>
<dt><code>show unwind-on-terminating-exception</code></dt>
<dd><a name="index-show-unwind_002don_002dterminating_002dexception"></a>
<p>Show the current setting of stack unwinding in the functions called by
<small>GDB</small>.
</p>
</dd>
<dt><code>set may-call-functions</code></dt>
<dd><a name="index-set-may_002dcall_002dfunctions"></a>
<a name="index-disabling-calling-functions-in-the-program"></a>
<a name="index-calling-functions-in-the-program_002c-disabling"></a>
<p>Set permission to call functions in the program.
This controls whether <small>GDB</small> will attempt to call functions in
the program, such as with expressions in the <code>print</code> command.  It
defaults to <code>on</code>.
</p>
<p>To call a function in the program, <small>GDB</small> has to temporarily
modify the state of the inferior.  This has potentially undesired side
effects.  Also, having <small>GDB</small> call nested functions is likely to
be erroneous and may even crash the program being debugged.  You can
avoid such hazards by forbidding <small>GDB</small> from calling functions
in the program being debugged.  If calling functions in the program
is forbidden, GDB will throw an error when a command (such as printing
an expression) starts a function call in the program.
</p>
</dd>
<dt><code>show may-call-functions</code></dt>
<dd><a name="index-show-may_002dcall_002dfunctions"></a>
<p>Show permission to call functions in the program.
</p>
</dd>
</dl>

<a name="Calling-Functions-with-No-Debug-Info"></a>
<h4 class="subsection">17.5.1 Calling Functions with No Debug Info</h4>

<a name="index-no-debug-info-functions"></a>
<p>Sometimes, a function you wish to call is missing debug information.
In such case, <small>GDB</small> does not know the type of the function,
including the types of the function&rsquo;s parameters.  To avoid calling
the inferior function incorrectly, which could result in the called
function functioning erroneously and even crash, <small>GDB</small> refuses
to call the function unless you tell it the type of the function.
</p>
<p>For prototyped (i.e. ANSI/ISO style) functions, there are two ways
to do that.  The simplest is to cast the call to the function&rsquo;s
declared return type.  For example:
</p>
<div class="smallexample">
<pre class="smallexample">(gdb) p getenv (&quot;PATH&quot;)
'getenv' has unknown return type; cast the call to its declared return type
(gdb) p (char *) getenv (&quot;PATH&quot;)
$1 = 0x7fffffffe7ba &quot;/usr/local/bin:/&quot;...
</pre></div>

<p>Casting the return type of a no-debug function is equivalent to
casting the function to a pointer to a prototyped function that has a
prototype that matches the types of the passed-in arguments, and
calling that.  I.e., the call above is equivalent to:
</p>
<div class="smallexample">
<pre class="smallexample">(gdb) p ((char * (*) (const char *)) getenv) (&quot;PATH&quot;)
</pre></div>

<p>and given this prototyped C or C++ function with float parameters:
</p>
<div class="smallexample">
<pre class="smallexample">float multiply (float v1, float v2) { return v1 * v2; }
</pre></div>

<p>these calls are equivalent:
</p>
<div class="smallexample">
<pre class="smallexample">(gdb) p (float) multiply (2.0f, 3.0f)
(gdb) p ((float (*) (float, float)) multiply) (2.0f, 3.0f)
</pre></div>

<p>If the function you wish to call is declared as unprototyped (i.e.
old K&amp;R style), you must use the cast-to-function-pointer syntax, so
that <small>GDB</small> knows that it needs to apply default argument
promotions (promote float arguments to double).  See <a href="ABI.html#ABI">float
promotion</a>.  For example, given this unprototyped C function with
float parameters, and no debug info:
</p>
<div class="smallexample">
<pre class="smallexample">float
multiply_noproto (v1, v2)
  float v1, v2;
{
  return v1 * v2;
}
</pre></div>

<p>you call it like this:
</p>
<div class="smallexample">
<pre class="smallexample">  (gdb) p ((float (*) ()) multiply_noproto) (2.0f, 3.0f)
</pre></div>

<hr>
<div class="header">
<p>
Next: <a href="Patching.html#Patching" accesskey="n" rel="next">Patching</a>, Previous: <a href="Returning.html#Returning" accesskey="p" rel="previous">Returning</a>, Up: <a href="Altering.html#Altering" accesskey="u" rel="up">Altering</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>