perlcall.html 138 KB
Newer Older
1 2 3
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
4 5
<head>
  <title>perlcall - perldoc.perl.org</title>
6 7
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  <meta http-equiv="Content-Language" content="en-gb">
8 9 10
  <link rel="search" type="application/opensearchdescription+xml" title="Search perldoc.perl.org" href="/static/search.xml"/>
  <link href="static/css-20100830.css" rel="stylesheet" rev="stylesheet" type="text/css" media="screen">
  <link href="static/exploreperl.css" rel="stylesheet" rev="stylesheet" type="text/css">
11 12
</head>

13 14 15 16 17 18 19
<body onLoad="perldoc.startup();" onPageShow="if (event.persisted) perldoc.startup();">
    <div id="page">
      
      <div id="header">
	<div id="homepage_link">
	  <a href="index.html"></a>
	</div>
20 21 22 23 24 25 26 27 28
	<div id="strapline">
	  Perl Programming Documentation
	</div>
	<div id="download_link" class="download">
	  <a href="http://www.perl.org/get.html">Download Perl</a>
	</div>
	<div id="explore_link" class="download">
	  <a id="explore_anchor" href="#">Explore</a>
	</div>
29
      </div>
30 31 32 33
      
      <div id="body">
        <div id="left_column">
          <div class="side_group">
34 35
            
	    <div class="side_panel doc_panel">
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
              <p>Manual</p>
              <ul>
                <li><a href="index-overview.html">Overview</a>
                <li><a href="index-tutorials.html">Tutorials</a>
                <li><a href="index-faq.html">FAQs</a>
                <li><a href="index-history.html">History / Changes</a>
                <li><a href="index-licence.html">License</a>
              </ul>
            </div>
            <div class="side_panel doc_panel">
              <p>Reference</p>
              <ul>
                <li><a href="index-language.html">Language</a>
                <li><a href="index-functions.html">Functions</a>
                <li><a href="perlop.html">Operators</a>
                <li><a href="perlvar.html">Special Variables</a>
                <li><a href="index-pragmas.html">Pragmas</a>
                <li><a href="index-utilities.html">Utilities</a>
54
                <li><a href="index-internals.html">Internals</a>
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276
                <li><a href="index-platforms.html">Platform Specific</a>
              </ul>
            </div>
            <div class="side_panel doc_panel">
              <p>Modules</p>
              <ul>
		<li>
		
                
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		
                  
		
		
                    <a href="index-modules-A.html">A</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-B.html">B</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-C.html">C</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-D.html">D</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-E.html">E</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-F.html">F</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-G.html">G</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-H.html">H</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-I.html">I</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-L.html">L</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-M.html">M</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-N.html">N</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-O.html">O</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-P.html">P</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-S.html">S</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-T.html">T</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-U.html">U</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-X.html">X</a>
                    
                
              </ul>
            </div>
277 278 279 280 281 282 283 284
            
	      <div class="side_panel doc_panel">
		<p>Tools</p>
		<ul>
		  <li><a href="preferences.html">Preferences</a>
		</ul>
	      </div>
            
285 286 287 288 289 290 291 292 293
          </div>
        </div>
        <div id="centre_column">
          <div id="content_header">
            <div id="title_bar">
              <div id="page_name">
                <h1>perlcall</h1>
              </div>
              <div id="perl_version">
294
                Perl 5 version 26.0 documentation
295
              </div>
296
              <div class="page_links" id="page_links_top">
297 298
                <a href="#" onClick="toolbar.goToTop();return false;">Go to top</a>
		
299 300
              </div>
	      <div class="page_links" id="page_links_bottom">
301
		
302
                  <a href="#" id="page_index_toggle">Show page index</a> &bull;
303
		
304 305 306 307 308 309 310
                <a href="#" id="recent_pages_toggle">Show recent pages</a>		
	      </div>
	      <div id="search_form">
		<form action="search.html" method="GET" id="search">
		  <input type="text" name="q" id="search_box" alt="Search">
		</form>
	      </div>
311 312 313 314 315 316 317 318 319 320 321
            </div>
            <div id="breadcrumbs">
                
    <a href="index.html">Home</a> &gt;
    
      
        <a href="index-internals.html">Internals and C language interface</a> &gt;
      
    
    perlcall
  
322

323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362
            </div>
          </div>
          <div id="content_body">
	    <!--[if lt IE 7]>
 <div class="noscript">
   <p>
     <strong>It looks like you're using Internet Explorer 6. This is a very old
     browser which does not offer full support for modern websites.</strong>
   </p>
   <p>
     Unfortunately this means that this website will not work on
     your computer.
   </p>
   <p>
     Don't miss out though! To view the site (and get a better experience from
     many other websites), simply upgrade to
     <a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet
Explorer 8</a>
     or download an alternative browser such as
     <a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>,
     <a href="http://www.apple.com/safari/download/">Safari</a>, or
     <a href="http://www.google.co.uk/chrome">Google Chrome</a>.
   </p>
   <p>
     All of these browsers are free. If you're using a PC at work, you may
     need to contact your IT administrator.
   </p>
 </div>
<![endif]-->
	    <noscript>
	      <div class="noscript">
	      <p>
                <strong>Please note: Many features of this site require JavaScript. You appear to have JavaScript disabled,
	        or are running a non-JavaScript capable web browser.</strong>
	      </p>
	      <p>
		To get the best experience, please enable JavaScript or download a modern web browser such as <a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet Explorer 8</a>, <a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>, <a href="http://www.apple.com/safari/download/">Safari</a>, or <a href="http://www.google.co.uk/chrome">Google Chrome</a>.
              </p>
	      </div>
	    </noscript>
363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378

	    <div id="recent_pages" class="hud_container">
	      <div id="recent_pages_header" class="hud_header">
		<div id="recent_pages_close" class="hud_close"><a href="#" onClick="recentPages.hide();return false;"></a></div>
		<div id="recent_pages_title" class="hud_title"><span class="hud_span_top">Recently read</span></div>
		<div id="recent_pages_topright" class="hud_topright"></div>
	      </div>
	      <div id="recent_pages_content" class="hud_content">
	      </div>
	      <div id="recent_pages_footer" class="hud_footer">
		<div id="recent_pages_bottomleft" class="hud_bottomleft"></div>
		<div id="recent_pages_bottom" class="hud_bottom"><span class="hud_span_bottom"></span></div>
		<div id="recent_pages_resize" class="hud_resize"></div>
	      </div>
	    </div>
  
379 380 381 382 383
	    <div id="from_search"></div>
            <h1>perlcall</h1>


  <!--    -->
384
<ul><li><a href="#NAME">NAME</a><li><a href="#DESCRIPTION">DESCRIPTION</a><li><a href="#THE-CALL_-FUNCTIONS">THE CALL_ FUNCTIONS</a><li><a href="#FLAG-VALUES">FLAG VALUES</a><ul><li><a href="#G_VOID">G_VOID</a><li><a href="#G_SCALAR">G_SCALAR</a><li><a href="#G_ARRAY">G_ARRAY</a><li><a href="#G_DISCARD">G_DISCARD</a><li><a href="#G_NOARGS">G_NOARGS</a><li><a href="#G_EVAL">G_EVAL</a><li><a href="#G_KEEPERR">G_KEEPERR</a><li><a href="#Determining-the-Context">Determining the Context</a></ul><li><a href="#EXAMPLES">EXAMPLES</a><ul><li><a href="#No-Parameters%2c-Nothing-Returned">No Parameters, Nothing Returned</a><li><a href="#Passing-Parameters">Passing Parameters</a><li><a href="#Returning-a-Scalar">Returning a Scalar</a><li><a href="#Returning-a-List-of-Values">Returning a List of Values</a><li><a href="#Returning-a-List-in-Scalar-Context">Returning a List in Scalar Context</a><li><a href="#Returning-Data-from-Perl-via-the-Parameter-List">Returning Data from Perl via the Parameter List</a><li><a href="#Using-G_EVAL">Using G_EVAL</a><li><a href="#Using-G_KEEPERR">Using G_KEEPERR</a><li><a href="#Using-call_sv">Using call_sv</a><li><a href="#Using-call_argv">Using call_argv</a><li><a href="#Using-call_method">Using call_method</a><li><a href="#Using-GIMME_V">Using GIMME_V</a><li><a href="#Using-Perl-to-Dispose-of-Temporaries">Using Perl to Dispose of Temporaries</a><li><a href="#Strategies-for-Storing-Callback-Context-Information">Strategies for Storing Callback Context Information</a><li><a href="#Alternate-Stack-Manipulation">Alternate Stack Manipulation</a><li><a href="#Creating-and-Calling-an-Anonymous-Subroutine-in-C">Creating and Calling an Anonymous Subroutine in C</a></ul><li><a href="#LIGHTWEIGHT-CALLBACKS">LIGHTWEIGHT CALLBACKS</a><li><a href="#SEE-ALSO">SEE ALSO</a><li><a href="#AUTHOR">AUTHOR</a><li><a href="#DATE">DATE</a></ul><a name="NAME"></a><h1>NAME</h1>
385 386 387 388 389 390 391 392 393 394 395
<p>perlcall - Perl calling conventions from C</p>
<a name="DESCRIPTION"></a><h1>DESCRIPTION</h1>
<p>The purpose of this document is to show you how to call Perl subroutines
directly from C, i.e., how to write <i>callbacks</i>.</p>
<p>Apart from discussing the C interface provided by Perl for writing
callbacks the document uses a series of examples to show how the
interface actually works in practice.  In addition some techniques for
coding callbacks are covered.</p>
<p>Examples where callbacks are necessary include</p>
<ul>
<li><a name="*-An-Error-Handler"></a><b>An Error Handler</b>
396
<p>You have created an XSUB interface to an application's C API.</p>
397 398 399 400 401
<p>A fairly common feature in applications is to allow you to define a C
function that will be called whenever something nasty occurs. What we
would like is to be able to specify a Perl subroutine that will be
called instead.</p>
</li>
402
<li><a name="*-An-Event-Driven-Program"></a><b>An Event-Driven Program</b>
403
<p>The classic example of where callbacks are used is when writing an
404
event driven program, such as for an X11 application.  In this case
405 406 407 408 409 410 411 412 413 414 415
you register functions to be called whenever specific events occur,
e.g., a mouse button is pressed, the cursor moves into a window or a
menu item is selected.</p>
</li>
</ul>
<p>Although the techniques described here are applicable when embedding
Perl in a C program, this is not the primary goal of this document.
There are other details that must be considered and are specific to
embedding Perl. For details on embedding Perl in C refer to
<a href="perlembed.html">perlembed</a>.</p>
<p>Before you launch yourself head first into the rest of this document,
416 417
it would be a good idea to have read the following two documents--<a href="perlxs.html">perlxs</a>
and <a href="perlguts.html">perlguts</a>.</p>
418 419 420 421 422
<a name="THE-CALL_-FUNCTIONS"></a><h1>THE CALL_ FUNCTIONS</h1>
<p>Although this stuff is easier to explain using examples, you first need
be aware of a few important definitions.</p>
<p>Perl has a number of C functions that allow you to call Perl
subroutines.  They are</p>
423
<pre class="verbatim"><ol><li>    <span class="w">I32</span> <span class="i">call_sv</span><span class="s">(</span><span class="w">SV</span>* <span class="w">sv</span><span class="cm">,</span> <span class="w">I32</span> <span class="w">flags</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="w">I32</span> <span class="i">call_pv</span><span class="s">(</span><span class="w">char</span> *<span class="w">subname</span><span class="cm">,</span> <span class="w">I32</span> <span class="w">flags</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="w">I32</span> <span class="i">call_method</span><span class="s">(</span><span class="w">char</span> *<span class="w">methname</span><span class="cm">,</span> <span class="w">I32</span> <span class="w">flags</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="w">I32</span> <span class="i">call_argv</span><span class="s">(</span><span class="w">char</span> *<span class="w">subname</span><span class="cm">,</span> <span class="w">I32</span> <span class="w">flags</span><span class="cm">,</span> <span class="w">char</span> **<span class="w">argv</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The key function is <i>call_sv</i>.  All the other functions are
424 425 426
fairly simple wrappers which make it easier to call Perl subroutines in
special cases. At the end of the day they will all call <i>call_sv</i>
to invoke the Perl subroutine.</p>
427
<p>All the <i>call_*</i> functions have a <code class="inline"><span class="w">flags</span></code>
428 429 430
 parameter which is
used to pass a bit mask of options to Perl.  This bit mask operates
identically for each of the functions.  The settings available in the
431
bit mask are discussed in <a href="#FLAG-VALUES">FLAG VALUES</a>.</p>
432 433 434
<p>Each of the functions will now be discussed in turn.</p>
<ul>
<li><a name="call_sv"></a><b>call_sv</b>
435
<p><i>call_sv</i> takes two parameters. The first, <code class="inline"><span class="w">sv</span></code>
436 437 438
, is an SV*.
This allows you to specify the Perl subroutine to be called either as a
C string (which has first been converted to an SV) or a reference to a
439
subroutine. The section, <a href="#Using-call_sv">Using call_sv</a>, shows how you can make
440 441 442 443 444 445 446 447 448 449 450 451 452
use of <i>call_sv</i>.</p>
</li>
<li><a name="call_pv"></a><b>call_pv</b>
<p>The function, <i>call_pv</i>, is similar to <i>call_sv</i> except it
expects its first parameter to be a C char* which identifies the Perl
subroutine you want to call, e.g., <code class="inline"><span class="i">call_pv</span><span class="s">(</span><span class="q">&quot;fred&quot;</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span></code>
.  If the
subroutine you want to call is in another package, just include the
package name in the string, e.g., <code class="inline"><span class="q">&quot;pkg::fred&quot;</span></code>
.</p>
</li>
<li><a name="call_method"></a><b>call_method</b>
<p>The function <i>call_method</i> is used to call a method from a Perl
453
class.  The parameter <code class="inline"><span class="w">methname</span></code>
454 455 456 457 458
 corresponds to the name of the method
to be called.  Note that the class that the method belongs to is passed
on the Perl stack rather than in the parameter list. This class can be
either the name of the class (for a static method) or a reference to an
object (for a virtual method).  See <a href="perlobj.html">perlobj</a> for more information on
459
static and virtual methods and <a href="#Using-call_method">Using call_method</a> for an example
460 461 462 463
of using <i>call_method</i>.</p>
</li>
<li><a name="call_argv"></a><b>call_argv</b>
<p><i>call_argv</i> calls the Perl subroutine specified by the C string
464 465
stored in the <code class="inline"><span class="w">subname</span></code>
 parameter. It also takes the usual <code class="inline"><span class="w">flags</span></code>
466

467
parameter.  The final parameter, <code class="inline"><span class="w">argv</span></code>
468
, consists of a NULL-terminated
469
list of C strings to be passed as parameters to the Perl subroutine.
470
See <a href="#Using-call_argv">Using call_argv</a>.</p>
471 472 473 474 475 476 477 478
</li>
</ul>
<p>All the functions return an integer. This is a count of the number of
items returned by the Perl subroutine. The actual items returned by the
subroutine are stored on the Perl stack.</p>
<p>As a general rule you should <i>always</i> check the return value from
these functions.  Even if you are expecting only a particular number of
values to be returned from the Perl subroutine, there is nothing to
479
stop someone from doing something unexpected--don't say you haven't
480 481
been warned.</p>
<a name="FLAG-VALUES"></a><h1>FLAG VALUES</h1>
482
<p>The <code class="inline"><span class="w">flags</span></code>
483 484 485
 parameter in all the <i>call_*</i> functions is one of G_VOID,
G_SCALAR, or G_ARRAY, which indicate the call context, OR'ed together
with a bit mask of any combination of the other G_* symbols defined below.</p>
486 487 488
<a name="G_VOID"></a><h2>G_VOID</h2>
<p>Calls the Perl subroutine in a void context.</p>
<p>This flag has 2 effects:</p>
489 490
<dl>
<dt>1.</dt><dd>
491 492 493
<p>It indicates to the subroutine being called that it is executing in
a void context (if it executes <i>wantarray</i> the result will be the
undefined value).</p>
494 495
</dd>
<dt>2.</dt><dd>
496
<p>It ensures that nothing is actually returned from the subroutine.</p>
497 498
</dd>
</dl>
499
<p>The value returned by the <i>call_*</i> function indicates how many
500
items have been returned by the Perl subroutine--in this case it will
501 502 503 504 505
be 0.</p>
<a name="G_SCALAR"></a><h2>G_SCALAR</h2>
<p>Calls the Perl subroutine in a scalar context.  This is the default
context flag setting for all the <i>call_*</i> functions.</p>
<p>This flag has 2 effects:</p>
506 507
<dl>
<dt>1.</dt><dd>
508 509
<p>It indicates to the subroutine being called that it is executing in a
scalar context (if it executes <i>wantarray</i> the result will be false).</p>
510 511
</dd>
<dt>2.</dt><dd>
512 513 514 515
<p>It ensures that only a scalar is actually returned from the subroutine.
The subroutine can, of course,  ignore the <i>wantarray</i> and return a
list anyway. If so, then only the last element of the list will be
returned.</p>
516 517
</dd>
</dl>
518 519 520 521 522
<p>The value returned by the <i>call_*</i> function indicates how many
items have been returned by the Perl subroutine - in this case it will
be either 0 or 1.</p>
<p>If 0, then you have specified the G_DISCARD flag.</p>
<p>If 1, then the item actually returned by the Perl subroutine will be
523
stored on the Perl stack - the section <a href="#Returning-a-Scalar">Returning a Scalar</a> shows how
524 525 526 527 528
to access this value on the stack.  Remember that regardless of how
many items the Perl subroutine returns, only the last one will be
accessible from the stack - think of the case where only one value is
returned as being a list with only one element.  Any other items that
were returned will not exist by the time control returns from the
529
<i>call_*</i> function.  The section <a href="#Returning-a-List-in-Scalar-Context">Returning a List in Scalar Context</a> shows an example of this behavior.</p>
530 531 532
<a name="G_ARRAY"></a><h2>G_ARRAY</h2>
<p>Calls the Perl subroutine in a list context.</p>
<p>As with G_SCALAR, this flag has 2 effects:</p>
533 534
<dl>
<dt>1.</dt><dd>
535 536
<p>It indicates to the subroutine being called that it is executing in a
list context (if it executes <i>wantarray</i> the result will be true).</p>
537 538
</dd>
<dt>2.</dt><dd>
539 540
<p>It ensures that all items returned from the subroutine will be
accessible when control returns from the <i>call_*</i> function.</p>
541 542
</dd>
</dl>
543 544 545 546 547
<p>The value returned by the <i>call_*</i> function indicates how many
items have been returned by the Perl subroutine.</p>
<p>If 0, then you have specified the G_DISCARD flag.</p>
<p>If not 0, then it will be a count of the number of items returned by
the subroutine. These items will be stored on the Perl stack.  The
548
section <a href="#Returning-a-List-of-Values">Returning a List of Values</a> gives an example of using the
549 550 551 552 553 554 555 556 557 558 559
G_ARRAY flag and the mechanics of accessing the returned items from the
Perl stack.</p>
<a name="G_DISCARD"></a><h2>G_DISCARD</h2>
<p>By default, the <i>call_*</i> functions place the items returned from
by the Perl subroutine on the stack.  If you are not interested in
these items, then setting this flag will make Perl get rid of them
automatically for you.  Note that it is still possible to indicate a
context to the Perl subroutine by using either G_SCALAR or G_ARRAY.</p>
<p>If you do not set this flag then it is <i>very</i> important that you make
sure that any temporaries (i.e., parameters passed to the Perl
subroutine and values returned from the subroutine) are disposed of
560 561
yourself.  The section <a href="#Returning-a-Scalar">Returning a Scalar</a> gives details of how to
dispose of these temporaries explicitly and the section <a href="#Using-Perl-to-Dispose-of-Temporaries">Using Perl to Dispose of Temporaries</a> discusses the specific circumstances where you
562 563 564 565 566 567 568 569 570 571
can ignore the problem and let Perl deal with it for you.</p>
<a name="G_NOARGS"></a><h2>G_NOARGS</h2>
<p>Whenever a Perl subroutine is called using one of the <i>call_*</i>
functions, it is assumed by default that parameters are to be passed to
the subroutine.  If you are not passing any parameters to the Perl
subroutine, you can save a bit of time by setting this flag.  It has
the effect of not creating the <code class="inline"><span class="i">@_</span></code>
 array for the Perl subroutine.</p>
<p>Although the functionality provided by this flag may seem
straightforward, it should be used only if there is a good reason to do
572
so.  The reason for being cautious is that, even if you have specified
573 574 575 576 577 578 579 580
the G_NOARGS flag, it is still possible for the Perl subroutine that
has been called to think that you have passed it parameters.</p>
<p>In fact, what can happen is that the Perl subroutine you have called
can access the <code class="inline"><span class="i">@_</span></code>
 array from a previous Perl subroutine.  This will
occur when the code that is executing the <i>call_*</i> function has
itself been called from another Perl subroutine. The code below
illustrates this</p>
581 582
<pre class="verbatim"><ol><li><a name="fred"></a>    sub <span class="m">fred</span></li><li>      <span class="s">{</span> <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;@_\n&quot;</span>  <span class="s">}</span></li><li></li><li><a name="joe"></a>    sub <span class="m">joe</span></li><li>      <span class="s">{</span> <span class="i">&amp;fred</span> <span class="s">}</span></li><li></li><li>    <span class="i">&amp;joe</span><span class="s">(</span><span class="n">1</span><span class="cm">,</span><span class="n">2</span><span class="cm">,</span><span class="n">3</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>This will print</p>
<pre class="verbatim"><ol><li>    1 2 3</li></ol></pre><p>What has happened is that <code class="inline"><span class="w">fred</span></code>
583 584
 accesses the <code class="inline"><span class="i">@_</span></code>
 array which
585
belongs to <code class="inline"><span class="w">joe</span></code>
586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620
.</p>
<a name="G_EVAL"></a><h2>G_EVAL</h2>
<p>It is possible for the Perl subroutine you are calling to terminate
abnormally, e.g., by calling <i>die</i> explicitly or by not actually
existing.  By default, when either of these events occurs, the
process will terminate immediately.  If you want to trap this
type of event, specify the G_EVAL flag.  It will put an <i>eval { }</i>
around the subroutine call.</p>
<p>Whenever control returns from the <i>call_*</i> function you need to
check the <code class="inline"><span class="i">$@</span></code>
 variable as you would in a normal Perl script.</p>
<p>The value returned from the <i>call_*</i> function is dependent on
what other flags have been specified and whether an error has
occurred.  Here are all the different cases that can occur:</p>
<ul>
<li>
<p>If the <i>call_*</i> function returns normally, then the value
returned is as specified in the previous sections.</p>
</li>
<li>
<p>If G_DISCARD is specified, the return value will always be 0.</p>
</li>
<li>
<p>If G_ARRAY is specified <i>and</i> an error has occurred, the return value
will always be 0.</p>
</li>
<li>
<p>If G_SCALAR is specified <i>and</i> an error has occurred, the return value
will be 1 and the value on the top of the stack will be <i>undef</i>. This
means that if you have already detected the error by checking <code class="inline"><span class="i">$@</span></code>
 and
you want the program to continue, you must remember to pop the <i>undef</i>
from the stack.</p>
</li>
</ul>
621
<p>See <a href="#Using-G_EVAL">Using G_EVAL</a> for details on using G_EVAL.</p>
622
<a name="G_KEEPERR"></a><h2>G_KEEPERR</h2>
623 624 625 626 627 628 629 630 631 632 633 634
<p>Using the G_EVAL flag described above will always set <code class="inline"><span class="i">$@</span></code>
: clearing
it if there was no error, and setting it to describe the error if there
was an error in the called code.  This is what you want if your intention
is to handle possible errors, but sometimes you just want to trap errors
and stop them interfering with the rest of the program.</p>
<p>This scenario will mostly be applicable to code that is meant to be called
from within destructors, asynchronous callbacks, and signal handlers.
In such situations, where the code being called has little relation to the
surrounding dynamic context, the main program needs to be insulated from
errors in the called code, even if they can't be handled intelligently.
It may also be useful to do this with code for <code class="inline"><span class="w">__DIE__</span></code>
635
 or <code class="inline"><span class="w">__WARN__</span></code>
636 637

hooks, and <code class="inline"><a class="l_k" href="functions/tie.html">tie</a></code> functions.</p>
638
<p>The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654
<i>call_*</i> functions that are used to implement such code, or with
<code class="inline"><span class="w">eval_sv</span></code>
.  This flag has no effect on the <code class="inline"><span class="w">call_</span>*</code>
 functions when
G_EVAL is not used.</p>
<p>When G_KEEPERR is used, any error in the called code will terminate the
call as usual, and the error will not propagate beyond the call (as usual
for G_EVAL), but it will not go into <code class="inline"><span class="i">$@</span></code>
.  Instead the error will be
converted into a warning, prefixed with the string "\t(in cleanup)".
This can be disabled using <code class="inline"><a class="l_k" href="functions/no.html">no</a> <span class="w">warnings</span> <span class="q">&#39;misc&#39;</span></code>
.  If there is no error,
<code class="inline"><span class="i">$@</span></code>
 will not be cleared.</p>
<p>Note that the G_KEEPERR flag does not propagate into inner evals; these
may still set <code class="inline"><span class="i">$@</span></code>
655 656
.</p>
<p>The G_KEEPERR flag was introduced in Perl version 5.002.</p>
657
<p>See <a href="#Using-G_KEEPERR">Using G_KEEPERR</a> for an example of a situation that warrants the
658 659 660 661
use of this flag.</p>
<a name="Determining-the-Context"></a><h2>Determining the Context</h2>
<p>As mentioned above, you can determine the context of the currently
executing subroutine in Perl with <i>wantarray</i>.  The equivalent test
662
can be made in C by using the <code class="inline"><span class="w">GIMME_V</span></code>
663
 macro, which returns
664 665
<code class="inline"><span class="w">G_ARRAY</span></code>
 if you have been called in a list context, <code class="inline"><span class="w">G_SCALAR</span></code>
666
 if
667
in a scalar context, or <code class="inline"><span class="w">G_VOID</span></code>
668
 if in a void context (i.e., the
669
return value will not be used).  An older version of this macro is
670 671
called <code class="inline"><span class="w">GIMME</span></code>
; in a void context it returns <code class="inline"><span class="w">G_SCALAR</span></code>
672
 instead of
673 674
<code class="inline"><span class="w">G_VOID</span></code>
.  An example of using the <code class="inline"><span class="w">GIMME_V</span></code>
675
 macro is shown in
676
section <a href="#Using-GIMME_V">Using GIMME_V</a>.</p>
677
<a name="EXAMPLES"></a><h1>EXAMPLES</h1>
678
<p>Enough of the definition talk! Let's have a few examples.</p>
679 680 681 682 683 684 685 686 687
<p>Perl provides many macros to assist in accessing the Perl stack.
Wherever possible, these macros should always be used when interfacing
to Perl internals.  We hope this should make the code less vulnerable
to any changes made to Perl in the future.</p>
<p>Another point worth noting is that in the first series of examples I
have made use of only the <i>call_pv</i> function.  This has been done
to keep the code simpler and ease you into the topic.  Wherever
possible, if the choice is between using <i>call_pv</i> and
<i>call_sv</i>, you should always try to use <i>call_sv</i>.  See
688
<a href="#Using-call_sv">Using call_sv</a> for details.</p>
689
<a name="No-Parameters%2c-Nothing-Returned"></a><h2>No Parameters, Nothing Returned</h2>
690 691
<p>This first trivial example will call a Perl subroutine, <i>PrintUID</i>, to
print out the UID of the process.</p>
692
<pre class="verbatim"><ol><li><a name="PrintUID"></a>    sub <span class="m">PrintUID</span></li><li>    <span class="s">{</span></li><li>        <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;UID is $&lt;\n&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>and here is a C function to call it</p>
693 694 695 696
<pre class="verbatim"><ol><li>    static void</li><li>    call_PrintUID()</li><li>    {</li><li>        dSP;</li><li></li><li>        PUSHMARK(SP);</li><li>        call_pv("PrintUID", G_DISCARD|G_NOARGS);</li><li>    }</li></ol></pre><p>Simple, eh?</p>
<p>A few points to note about this example:</p>
<dl>
<dt>1.</dt><dd>
697 698
<p>Ignore <code class="inline"><span class="w">dSP</span></code>
 and <code class="inline"><span class="i">PUSHMARK</span><span class="s">(</span><span class="w">SP</span><span class="s">)</span></code>
699 700
 for now. They will be discussed in
the next example.</p>
701 702 703
</dd>
<dt>2.</dt><dd>
<p>We aren't passing any parameters to <i>PrintUID</i> so G_NOARGS can be
704
specified.</p>
705 706 707
</dd>
<dt>3.</dt><dd>
<p>We aren't interested in anything returned from <i>PrintUID</i>, so
708 709 710
G_DISCARD is specified. Even if <i>PrintUID</i> was changed to
return some value(s), having specified G_DISCARD will mean that they
will be wiped by the time control returns from <i>call_pv</i>.</p>
711 712
</dd>
<dt>4.</dt><dd>
713
<p>As <i>call_pv</i> is being used, the Perl subroutine is specified as a
714
C string. In this case the subroutine name has been 'hard-wired' into the
715
code.</p>
716 717
</dd>
<dt>5.</dt><dd>
718 719
<p>Because we specified G_DISCARD, it is not necessary to check the value
returned from <i>call_pv</i>. It will always be 0.</p>
720 721
</dd>
</dl>
722
<a name="Passing-Parameters"></a><h2>Passing Parameters</h2>
723
<p>Now let's make a slightly more complex example. This time we want to
724
call a Perl subroutine, <code class="inline"><span class="w">LeftString</span></code>
725 726 727
, which will take 2 parameters--a
string ($s) and an integer ($n).  The subroutine will simply
print the first $n characters of the string.</p>
728 729
<p>So the Perl subroutine would look like this:</p>
<pre class="verbatim"><ol><li><a name="LeftString"></a>    sub <span class="m">LeftString</span></li><li>    <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a><span class="s">(</span><span class="i">$s</span><span class="cm">,</span> <span class="i">$n</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/print.html">print</a> <a class="l_k" href="functions/substr.html">substr</a><span class="s">(</span><span class="i">$s</span><span class="cm">,</span> <span class="n">0</span><span class="cm">,</span> <span class="i">$n</span><span class="s">)</span><span class="cm">,</span> <span class="q">&quot;\n&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>The C function required to call <i>LeftString</i> would look like this:</p>
730
<pre class="verbatim"><ol><li>    <span class="w">static</span> <span class="w">void</span></li><li>    <span class="i">call_LeftString</span><span class="s">(</span><span class="w">a</span><span class="cm">,</span> <span class="w">b</span><span class="s">)</span></li><li>    <span class="w">char</span> * <span class="w">a</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/int.html">int</a> <span class="w">b</span><span class="sc">;</span></li><li>    <span class="s">{</span></li><li>        <span class="w">dSP</span><span class="sc">;</span></li><li></li><li>	<span class="w">ENTER</span><span class="sc">;</span></li><li>        <span class="w">SAVETMPS</span><span class="sc">;</span></li><li></li><li>        <span class="i">PUSHMARK</span><span class="s">(</span><span class="w">SP</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">EXTEND</span><span class="s">(</span><span class="w">SP</span><span class="cm">,</span> <span class="n">2</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSVpv</span><span class="s">(</span><span class="w">a</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><span class="w">b</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="w">PUTBACK</span><span class="sc">;</span></li><li></li><li>        <span class="i">call_pv</span><span class="s">(</span><span class="q">&quot;LeftString&quot;</span><span class="cm">,</span> <span class="w">G_DISCARD</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <span class="w">FREETMPS</span><span class="sc">;</span></li><li>        <span class="w">LEAVE</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Here are a few notes on the C function <i>call_LeftString</i>.</p>
731 732
<dl>
<dt>1.</dt><dd>
733
<p>Parameters are passed to the Perl subroutine using the Perl stack.
734
This is the purpose of the code beginning with the line <code class="inline"><span class="w">dSP</span></code>
735
 and
736 737
ending with the line <code class="inline"><span class="w">PUTBACK</span></code>
.  The <code class="inline"><span class="w">dSP</span></code>
738 739
 declares a local copy
of the stack pointer.  This local copy should <b>always</b> be accessed
740
as <code class="inline"><span class="w">SP</span></code>
741
.</p>
742 743
</dd>
<dt>2.</dt><dd>
744
<p>If you are going to put something onto the Perl stack, you need to know
745
where to put it. This is the purpose of the macro <code class="inline"><span class="w">dSP</span></code>
746 747 748 749 750 751
--it declares
and initializes a <i>local</i> copy of the Perl stack pointer.</p>
<p>All the other macros which will be used in this example require you to
have used this macro.</p>
<p>The exception to this rule is if you are calling a Perl subroutine
directly from an XSUB function. In this case it is not necessary to
752
use the <code class="inline"><span class="w">dSP</span></code>
753 754
 macro explicitly--it will be declared for you
automatically.</p>
755 756
</dd>
<dt>3.</dt><dd>
757
<p>Any parameters to be pushed onto the stack should be bracketed by the
758 759
<code class="inline"><span class="w">PUSHMARK</span></code>
 and <code class="inline"><span class="w">PUTBACK</span></code>
760 761 762 763 764
 macros.  The purpose of these two macros, in
this context, is to count the number of parameters you are
pushing automatically.  Then whenever Perl is creating the <code class="inline"><span class="i">@_</span></code>
 array for the
subroutine, it knows how big to make it.</p>
765
<p>The <code class="inline"><span class="w">PUSHMARK</span></code>
766
 macro tells Perl to make a mental note of the current
767
stack pointer. Even if you aren't passing any parameters (like the
768
example shown in the section <a href="#No-Parameters%2c-Nothing-Returned">No Parameters, Nothing Returned</a>) you
769
must still call the <code class="inline"><span class="w">PUSHMARK</span></code>
770 771 772
 macro before you can call any of the
<i>call_*</i> functions--Perl still needs to know that there are no
parameters.</p>
773
<p>The <code class="inline"><span class="w">PUTBACK</span></code>
774
 macro sets the global copy of the stack pointer to be
775 776
the same as our local copy. If we didn't do this, <i>call_pv</i>
wouldn't know where the two parameters we pushed were--remember that
777 778
up to now all the stack pointer manipulation we have done is with our
local copy, <i>not</i> the global copy.</p>
779 780
</dd>
<dt>4.</dt><dd>
781 782 783 784 785 786 787 788
<p>Next, we come to EXTEND and PUSHs. This is where the parameters
actually get pushed onto the stack. In this case we are pushing a
string and an integer.</p>
<p>Alternatively you can use the XPUSHs() macro, which combines a
<code class="inline"><span class="i">EXTEND</span><span class="s">(</span><span class="w">SP</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span></code>
 and <code class="inline"><span class="i">PUSHs</span><span class="s">(</span><span class="s">)</span></code>
.  This is less efficient if you're
pushing multiple values.</p>
789
<p>See <a href="perlguts.html#XSUBs-and-the-Argument-Stack">XSUBs and the Argument Stack in perlguts</a> for details
790
on how the PUSH macros work.</p>
791 792
</dd>
<dt>5.</dt><dd>
793 794 795
<p>Because we created temporary values (by means of sv_2mortal() calls)
we will have to tidy up the Perl stack and dispose of mortal SVs.</p>
<p>This is the purpose of</p>
796 797
<pre class="verbatim"><ol><li>    <span class="w">ENTER</span><span class="sc">;</span></li><li>    <span class="w">SAVETMPS</span><span class="sc">;</span></li></ol></pre><p>at the start of the function, and</p>
<pre class="verbatim"><ol><li>    <span class="w">FREETMPS</span><span class="sc">;</span></li><li>    <span class="w">LEAVE</span><span class="sc">;</span></li></ol></pre><p>at the end. The <code class="inline"><span class="w">ENTER</span></code>
798
/<code class="inline"><span class="w">SAVETMPS</span></code>
799 800 801
 pair creates a boundary for any
temporaries we create.  This means that the temporaries we get rid of
will be limited to those which were created after these calls.</p>
802 803
<p>The <code class="inline"><span class="w">FREETMPS</span></code>
/<code class="inline"><span class="w">LEAVE</span></code>
804 805
 pair will get rid of any values returned by
the Perl subroutine (see next example), plus it will also dump the
806 807
mortal SVs we have created.  Having <code class="inline"><span class="w">ENTER</span></code>
/<code class="inline"><span class="w">SAVETMPS</span></code>
808 809
 at the
beginning of the code makes sure that no other mortals are destroyed.</p>
810
<p>Think of these macros as working a bit like <code class="inline">{</code> and <code class="inline">}</code> in Perl
811
to limit the scope of local variables.</p>
812
<p>See the section <a href="#Using-Perl-to-Dispose-of-Temporaries">Using Perl to Dispose of Temporaries</a> for details of
813
an alternative to using these macros.</p>
814 815
</dd>
<dt>6.</dt><dd>
816 817 818 819
<p>Finally, <i>LeftString</i> can now be called via the <i>call_pv</i> function.
The only flag specified this time is G_DISCARD. Because we are passing
2 parameters to the Perl subroutine this time, we have not specified
G_NOARGS.</p>
820 821
</dd>
</dl>
822 823 824 825 826
<a name="Returning-a-Scalar"></a><h2>Returning a Scalar</h2>
<p>Now for an example of dealing with the items returned from a Perl
subroutine.</p>
<p>Here is a Perl subroutine, <i>Adder</i>, that takes 2 integer parameters
and simply returns their sum.</p>
827
<pre class="verbatim"><ol><li><a name="Adder"></a>    sub <span class="m">Adder</span></li><li>    <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>        <span class="i">$a</span> + <span class="i">$b</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Because we are now concerned with the return value from <i>Adder</i>, the C
828
function required to call it is now a bit more complex.</p>
829
<pre class="verbatim"><ol><li>    <span class="w">static</span> <span class="w">void</span></li><li>    <span class="i">call_Adder</span><span class="s">(</span><span class="w">a</span><span class="cm">,</span> <span class="w">b</span><span class="s">)</span></li><li>    <a class="l_k" href="functions/int.html">int</a> <span class="w">a</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/int.html">int</a> <span class="w">b</span><span class="sc">;</span></li><li>    <span class="s">{</span></li><li>        <span class="w">dSP</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/int.html">int</a> <span class="w">count</span><span class="sc">;</span></li><li></li><li>        <span class="w">ENTER</span><span class="sc">;</span></li><li>        <span class="w">SAVETMPS</span><span class="sc">;</span></li><li></li><li>        <span class="i">PUSHMARK</span><span class="s">(</span><span class="w">SP</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">EXTEND</span><span class="s">(</span><span class="w">SP</span><span class="cm">,</span> <span class="n">2</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><span class="w">a</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><span class="w">b</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="w">PUTBACK</span><span class="sc">;</span></li><li></li><li>        <span class="w">count</span> = <span class="i">call_pv</span><span class="s">(</span><span class="q">&quot;Adder&quot;</span><span class="cm">,</span> <span class="w">G_SCALAR</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <span class="w">SPAGAIN</span><span class="sc">;</span></li><li></li><li>        <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="w">count</span> != <span class="n">1</span><span class="s">)</span></li><li>            <span class="i">croak</span><span class="s">(</span><span class="q">&quot;Big trouble\n&quot;</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;The sum of %d and %d is %d\n&quot;</span><span class="cm">,</span> <span class="w">a</span><span class="cm">,</span> <span class="w">b</span><span class="cm">,</span> <span class="w">POPi</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <span class="w">PUTBACK</span><span class="sc">;</span></li><li>        <span class="w">FREETMPS</span><span class="sc">;</span></li><li>        <span class="w">LEAVE</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Points to note this time are</p>
830 831 832
<dl>
<dt>1.</dt><dd>
<p>The only flag specified this time was G_SCALAR. That means that the <code class="inline"><span class="i">@_</span></code>
833 834 835

array will be created and that the value returned by <i>Adder</i> will
still exist after the call to <i>call_pv</i>.</p>
836 837
</dd>
<dt>2.</dt><dd>
838
<p>The purpose of the macro <code class="inline"><span class="w">SPAGAIN</span></code>
839 840
 is to refresh the local copy of the
stack pointer. This is necessary because it is possible that the memory
841
allocated to the Perl stack has been reallocated during the
842 843 844 845
<i>call_pv</i> call.</p>
<p>If you are making use of the Perl stack pointer in your code you must
always refresh the local copy using SPAGAIN whenever you make use
of the <i>call_*</i> functions or any other Perl internal function.</p>
846 847
</dd>
<dt>3.</dt><dd>
848 849 850 851 852
<p>Although only a single value was expected to be returned from <i>Adder</i>,
it is still good practice to check the return code from <i>call_pv</i>
anyway.</p>
<p>Expecting a single value is not quite the same as knowing that there
will be one. If someone modified <i>Adder</i> to return a list and we
853
didn't check for that possibility and take appropriate action the Perl
854
stack would end up in an inconsistent state. That is something you
855 856 857
<i>really</i> don't want to happen ever.</p>
</dd>
<dt>4.</dt><dd>
858
<p>The <code class="inline"><span class="w">POPi</span></code>
859
 macro is used here to pop the return value from the stack.
860
In this case we wanted an integer, so <code class="inline"><span class="w">POPi</span></code>
861 862 863
 was used.</p>
<p>Here is the complete list of POP macros available, along with the types
they return.</p>
864 865 866 867 868
<pre class="verbatim"><ol><li>    <span class="w">POPs</span>	<span class="w">SV</span></li><li>    <span class="w">POPp</span>	<span class="w">pointer</span> <span class="s">(</span><span class="w">PV</span><span class="s">)</span></li><li>    <span class="w">POPpbytex</span>   <span class="w">pointer</span> <span class="w">to</span> <span class="w">bytes</span> <span class="s">(</span><span class="w">PV</span><span class="s">)</span></li><li>    <span class="w">POPn</span>	<span class="w">double</span> <span class="s">(</span><span class="w">NV</span><span class="s">)</span></li><li>    <span class="w">POPi</span>	<span class="w">integer</span> <span class="s">(</span><span class="w">IV</span><span class="s">)</span></li><li>    <span class="w">POPu</span>        <span class="w">unsigned</span> <span class="w">integer</span> <span class="s">(</span><span class="w">UV</span><span class="s">)</span></li><li>    <span class="w">POPl</span>	<span class="w">long</span></li><li>    <span class="w">POPul</span>       <span class="w">unsigned</span> <span class="w">long</span></li></ol></pre><p>Since these macros have side-effects don't use them as arguments to
macros that may evaluate their argument several times, for example:</p>
<pre class="verbatim"><ol><li>  <span class="q">/* Bad idea, don&#39;t do this */</span></li><li>  <span class="w">STRLEN</span> <span class="w">len</span><span class="sc">;</span></li><li>  <span class="w">const</span> <span class="w">char</span> *<span class="q">s = SvPV(POPs, len);</span></li></ol></pre><p>Instead, use a temporary:</p>
<pre class="verbatim"><ol><li>  <span class="w">STRLEN</span> <span class="w">len</span><span class="sc">;</span></li><li>  <span class="w">SV</span> *<span class="w">sv</span> = <span class="w">POPs</span><span class="sc">;</span></li><li>  <span class="w">const</span> <span class="w">char</span> *<span class="q">s = SvPV(sv, len);</span></li></ol></pre><p>or a macro that guarantees it will evaluate its arguments only once:</p>
<pre class="verbatim"><ol><li>  <span class="w">STRLEN</span> <span class="w">len</span><span class="sc">;</span></li><li>  <span class="w">const</span> <span class="w">char</span> *<span class="q">s = SvPVx(POPs, len);</span></li></ol></pre></dd>
869
<dt>5.</dt><dd>
870
<p>The final <code class="inline"><span class="w">PUTBACK</span></code>
871 872
 is used to leave the Perl stack in a consistent
state before exiting the function.  This is necessary because when we
873
popped the return value from the stack with <code class="inline"><span class="w">POPi</span></code>
874
 it updated only our
875
local copy of the stack pointer.  Remember, <code class="inline"><span class="w">PUTBACK</span></code>
876 877
 sets the global
stack pointer to be the same as our local copy.</p>
878 879 880 881
</dd>
</dl>
<a name="Returning-a-List-of-Values"></a><h2>Returning a List of Values</h2>
<p>Now, let's extend the previous example to return both the sum of the
882 883
parameters and the difference.</p>
<p>Here is the Perl subroutine</p>
884
<pre class="verbatim"><ol><li><a name="AddSubtract"></a>    sub <span class="m">AddSubtract</span></li><li>    <span class="s">{</span></li><li>       <a class="l_k" href="functions/my.html">my</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>       <span class="s">(</span><span class="i">$a</span>+<span class="i">$b</span><span class="cm">,</span> <span class="i">$a</span>-<span class="i">$b</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>and this is the C function</p>
885
<pre class="verbatim"><ol><li>    <span class="w">static</span> <span class="w">void</span></li><li>    <span class="i">call_AddSubtract</span><span class="s">(</span><span class="w">a</span><span class="cm">,</span> <span class="w">b</span><span class="s">)</span></li><li>    <a class="l_k" href="functions/int.html">int</a> <span class="w">a</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/int.html">int</a> <span class="w">b</span><span class="sc">;</span></li><li>    <span class="s">{</span></li><li>        <span class="w">dSP</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/int.html">int</a> <span class="w">count</span><span class="sc">;</span></li><li></li><li>        <span class="w">ENTER</span><span class="sc">;</span></li><li>        <span class="w">SAVETMPS</span><span class="sc">;</span></li><li></li><li>        <span class="i">PUSHMARK</span><span class="s">(</span><span class="w">SP</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">EXTEND</span><span class="s">(</span><span class="w">SP</span><span class="cm">,</span> <span class="n">2</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><span class="w">a</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><span class="w">b</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="w">PUTBACK</span><span class="sc">;</span></li><li></li><li>        <span class="w">count</span> = <span class="i">call_pv</span><span class="s">(</span><span class="q">&quot;AddSubtract&quot;</span><span class="cm">,</span> <span class="w">G_ARRAY</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <span class="w">SPAGAIN</span><span class="sc">;</span></li><li></li><li>        <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="w">count</span> != <span class="n">2</span><span class="s">)</span></li><li>            <span class="i">croak</span><span class="s">(</span><span class="q">&quot;Big trouble\n&quot;</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;%d - %d = %d\n&quot;</span><span class="cm">,</span> <span class="w">a</span><span class="cm">,</span> <span class="w">b</span><span class="cm">,</span> <span class="w">POPi</span><span class="s">)</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;%d + %d = %d\n&quot;</span><span class="cm">,</span> <span class="w">a</span><span class="cm">,</span> <span class="w">b</span><span class="cm">,</span> <span class="w">POPi</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <span class="w">PUTBACK</span><span class="sc">;</span></li><li>        <span class="w">FREETMPS</span><span class="sc">;</span></li><li>        <span class="w">LEAVE</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>If <i>call_AddSubtract</i> is called like this</p>
886 887
<pre class="verbatim"><ol><li>    <span class="i">call_AddSubtract</span><span class="s">(</span><span class="n">7</span><span class="cm">,</span> <span class="n">4</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>then here is the output</p>
<pre class="verbatim"><ol><li>    7 - 4 = 3</li><li>    7 + 4 = 11</li></ol></pre><p>Notes</p>
888 889
<dl>
<dt>1.</dt><dd>
890
<p>We wanted list context, so G_ARRAY was used.</p>
891 892
</dd>
<dt>2.</dt><dd>
893
<p>Not surprisingly <code class="inline"><span class="w">POPi</span></code>
894 895
 is used twice this time because we were
retrieving 2 values from the stack. The important thing to note is that
896
when using the <code class="inline"><span class="w">POP</span>*</code>
897 898
 macros they come off the stack in <i>reverse</i>
order.</p>
899 900
</dd>
</dl>
901
<a name="Returning-a-List-in-Scalar-Context"></a><h2>Returning a List in Scalar Context</h2>
902 903
<p>Say the Perl subroutine in the previous section was called in a scalar
context, like this</p>
904
<pre class="verbatim"><ol><li>    <span class="w">static</span> <span class="w">void</span></li><li>    <span class="i">call_AddSubScalar</span><span class="s">(</span><span class="w">a</span><span class="cm">,</span> <span class="w">b</span><span class="s">)</span></li><li>    <a class="l_k" href="functions/int.html">int</a> <span class="w">a</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/int.html">int</a> <span class="w">b</span><span class="sc">;</span></li><li>    <span class="s">{</span></li><li>        <span class="w">dSP</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/int.html">int</a> <span class="w">count</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/int.html">int</a> <span class="w">i</span><span class="sc">;</span></li><li></li><li>        <span class="w">ENTER</span><span class="sc">;</span></li><li>        <span class="w">SAVETMPS</span><span class="sc">;</span></li><li></li><li>        <span class="i">PUSHMARK</span><span class="s">(</span><span class="w">SP</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">EXTEND</span><span class="s">(</span><span class="w">SP</span><span class="cm">,</span> <span class="n">2</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><span class="w">a</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><span class="w">b</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="w">PUTBACK</span><span class="sc">;</span></li><li></li><li>        <span class="w">count</span> = <span class="i">call_pv</span><span class="s">(</span><span class="q">&quot;AddSubtract&quot;</span><span class="cm">,</span> <span class="w">G_SCALAR</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <span class="w">SPAGAIN</span><span class="sc">;</span></li><li></li><li>        <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;Items Returned = %d\n&quot;</span><span class="cm">,</span> <span class="w">count</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <a class="l_k" href="functions/for.html">for</a> <span class="s">(</span><span class="w">i</span> = <span class="n">1</span><span class="sc">;</span> <span class="w">i</span> &lt;= <span class="w">count</span><span class="sc">;</span> ++<span class="w">i</span><span class="s">)</span></li><li>            <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;Value %d = %d\n&quot;</span><span class="cm">,</span> <span class="w">i</span><span class="cm">,</span> <span class="w">POPi</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <span class="w">PUTBACK</span><span class="sc">;</span></li><li>        <span class="w">FREETMPS</span><span class="sc">;</span></li><li>        <span class="w">LEAVE</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>The other modification made is that <i>call_AddSubScalar</i> will print the
905 906 907
number of items returned from the Perl subroutine and their value (for
simplicity it assumes that they are integer).  So if
<i>call_AddSubScalar</i> is called</p>
908 909
<pre class="verbatim"><ol><li>    <span class="i">call_AddSubScalar</span><span class="s">(</span><span class="n">7</span><span class="cm">,</span> <span class="n">4</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>then the output will be</p>
<pre class="verbatim"><ol><li>    Items Returned = 1</li><li>    Value 1 = 3</li></ol></pre><p>In this case the main point to note is that only the last item in the
910
list is returned from the subroutine. <i>AddSubtract</i> actually made it back to
911
<i>call_AddSubScalar</i>.</p>
912 913 914
<a name="Returning-Data-from-Perl-via-the-Parameter-List"></a><h2>Returning Data from Perl via the Parameter List</h2>
<p>It is also possible to return values directly via the parameter
list--whether it is actually desirable to do it is another matter entirely.</p>
915 916
<p>The Perl subroutine, <i>Inc</i>, below takes 2 parameters and increments
each directly.</p>
917
<pre class="verbatim"><ol><li><a name="Inc"></a>    sub <span class="m">Inc</span></li><li>    <span class="s">{</span></li><li>        ++ <span class="i">$_</span>[<span class="n">0</span>]<span class="sc">;</span></li><li>        ++ <span class="i">$_</span>[<span class="n">1</span>]<span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>and here is a C function to call it.</p>
918
<pre class="verbatim"><ol><li>    <span class="w">static</span> <span class="w">void</span></li><li>    <span class="i">call_Inc</span><span class="s">(</span><span class="w">a</span><span class="cm">,</span> <span class="w">b</span><span class="s">)</span></li><li>    <a class="l_k" href="functions/int.html">int</a> <span class="w">a</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/int.html">int</a> <span class="w">b</span><span class="sc">;</span></li><li>    <span class="s">{</span></li><li>        <span class="w">dSP</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/int.html">int</a> <span class="w">count</span><span class="sc">;</span></li><li>        <span class="w">SV</span> * <span class="w">sva</span><span class="sc">;</span></li><li>        <span class="w">SV</span> * <span class="w">svb</span><span class="sc">;</span></li><li></li><li>        <span class="w">ENTER</span><span class="sc">;</span></li><li>        <span class="w">SAVETMPS</span><span class="sc">;</span></li><li></li><li>        <span class="w">sva</span> = <span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><span class="w">a</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="w">svb</span> = <span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><span class="w">b</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <span class="i">PUSHMARK</span><span class="s">(</span><span class="w">SP</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">EXTEND</span><span class="s">(</span><span class="w">SP</span><span class="cm">,</span> <span class="n">2</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><span class="w">sva</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><span class="w">svb</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="w">PUTBACK</span><span class="sc">;</span></li><li></li><li>        <span class="w">count</span> = <span class="i">call_pv</span><span class="s">(</span><span class="q">&quot;Inc&quot;</span><span class="cm">,</span> <span class="w">G_DISCARD</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="w">count</span> != <span class="n">0</span><span class="s">)</span></li><li>            <span class="w">croak</span> <span class="s">(</span><span class="q">&quot;call_Inc: expected 0 values from &#39;Inc&#39;, got %d\n&quot;</span><span class="cm">,</span></li><li>                   <span class="w">count</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>        <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;%d + 1 = %d\n&quot;</span><span class="cm">,</span> <span class="w">a</span><span class="cm">,</span> <span class="i">SvIV</span><span class="s">(</span><span class="w">sva</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;%d + 1 = %d\n&quot;</span><span class="cm">,</span> <span class="w">b</span><span class="cm">,</span> <span class="i">SvIV</span><span class="s">(</span><span class="w">svb</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>	<span class="w">FREETMPS</span><span class="sc">;</span></li><li>	<span class="w">LEAVE</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>To be able to access the two parameters that were pushed onto the stack
919
after they return from <i>call_pv</i> it is necessary to make a note
920 921
of their addresses--thus the two variables <code class="inline"><span class="w">sva</span></code>
 and <code class="inline"><span class="w">svb</span></code>
922 923 924 925 926 927 928 929
.</p>
<p>The reason this is necessary is that the area of the Perl stack which
held them will very likely have been overwritten by something else by
the time control returns from <i>call_pv</i>.</p>
<a name="Using-G_EVAL"></a><h2>Using G_EVAL</h2>
<p>Now an example using G_EVAL. Below is a Perl subroutine which computes
the difference of its 2 parameters. If this would result in a negative
result, the subroutine calls <i>die</i>.</p>
930
<pre class="verbatim"><ol><li><a name="Subtract"></a>    sub <span class="m">Subtract</span></li><li>    <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="i">$b</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li></li><li>        <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;death can be fatal\n&quot;</span> if <span class="i">$a</span> &lt; <span class="i">$b</span><span class="sc">;</span></li><li></li><li>        <span class="i">$a</span> - <span class="i">$b</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>and some C to call it</p>
931
<pre class="verbatim"><ol><li> <span class="w">static</span> <span class="w">void</span></li><li> <span class="i">call_Subtract</span><span class="s">(</span><span class="w">a</span><span class="cm">,</span> <span class="w">b</span><span class="s">)</span></li><li> <a class="l_k" href="functions/int.html">int</a> <span class="w">a</span><span class="sc">;</span></li><li> <a class="l_k" href="functions/int.html">int</a> <span class="w">b</span><span class="sc">;</span></li><li> <span class="s">{</span></li><li>     <span class="w">dSP</span><span class="sc">;</span></li><li>     <a class="l_k" href="functions/int.html">int</a> <span class="w">count</span><span class="sc">;</span></li><li>     <span class="w">SV</span> *<span class="w">err_tmp</span><span class="sc">;</span></li><li></li><li>     <span class="w">ENTER</span><span class="sc">;</span></li><li>     <span class="w">SAVETMPS</span><span class="sc">;</span></li><li></li><li>     <span class="i">PUSHMARK</span><span class="s">(</span><span class="w">SP</span><span class="s">)</span><span class="sc">;</span></li><li>     <span class="i">EXTEND</span><span class="s">(</span><span class="w">SP</span><span class="cm">,</span> <span class="n">2</span><span class="s">)</span><span class="sc">;</span></li><li>     <span class="i">PUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><span class="w">a</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>     <span class="i">PUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><span class="w">b</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>     <span class="w">PUTBACK</span><span class="sc">;</span></li><li></li><li>     <span class="w">count</span> = <span class="i">call_pv</span><span class="s">(</span><span class="q">&quot;Subtract&quot;</span><span class="cm">,</span> <span class="w">G_EVAL</span>|<span class="w">G_SCALAR</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>     <span class="w">SPAGAIN</span><span class="sc">;</span></li><li></li><li>     <span class="q">/* Check the eval first */</span></li><li>     <span class="w">err_tmp</span> = <span class="w">ERRSV</span><span class="sc">;</span></li><li>     <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="i">SvTRUE</span><span class="s">(</span><span class="w">err_tmp</span><span class="s">)</span><span class="s">)</span></li><li>     <span class="s">{</span></li><li>         <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;Uh oh - %s\n&quot;</span><span class="cm">,</span> <span class="i">SvPV_nolen</span><span class="s">(</span><span class="w">err_tmp</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>         <span class="w">POPs</span><span class="sc">;</span></li><li>     <span class="s">}</span></li><li>     <a class="l_k" href="functions/else.html">else</a></li><li>     <span class="s">{</span></li><li>       <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="w">count</span> != <span class="n">1</span><span class="s">)</span></li><li>        <span class="i">croak</span><span class="s">(</span><span class="q">&quot;call_Subtract: wanted 1 value from &#39;Subtract&#39;, got %d\n&quot;</span><span class="cm">,</span></li><li>              <span class="w">count</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>         <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;%d - %d = %d\n&quot;</span><span class="cm">,</span> <span class="w">a</span><span class="cm">,</span> <span class="w">b</span><span class="cm">,</span> <span class="w">POPi</span><span class="s">)</span><span class="sc">;</span></li><li>     <span class="s">}</span></li><li></li><li>     <span class="w">PUTBACK</span><span class="sc">;</span></li><li>     <span class="w">FREETMPS</span><span class="sc">;</span></li><li>     <span class="w">LEAVE</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>If <i>call_Subtract</i> is called thus</p>
932 933
<pre class="verbatim"><ol><li>    <span class="i">call_Subtract</span><span class="s">(</span><span class="n">4</span><span class="cm">,</span> <span class="n">5</span><span class="s">)</span></li></ol></pre><p>the following will be printed</p>
<pre class="verbatim"><ol><li>    <span class="w">Uh</span> <span class="w">oh</span> - <span class="w">death</span> <span class="w">can</span> <span class="w">be</span> <span class="w">fatal</span></li></ol></pre><p>Notes</p>
934 935
<dl>
<dt>1.</dt><dd>
936 937 938 939
<p>We want to be able to catch the <i>die</i> so we have used the G_EVAL
flag.  Not specifying this flag would mean that the program would
terminate immediately at the <i>die</i> statement in the subroutine
<i>Subtract</i>.</p>
940 941
</dd>
<dt>2.</dt><dd>
942
<p>The code</p>
943
<pre class="verbatim"><ol><li>    <span class="w">err_tmp</span> = <span class="w">ERRSV</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="i">SvTRUE</span><span class="s">(</span><span class="w">err_tmp</span><span class="s">)</span><span class="s">)</span></li><li>    <span class="s">{</span></li><li>        <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;Uh oh - %s\n&quot;</span><span class="cm">,</span> <span class="i">SvPV_nolen</span><span class="s">(</span><span class="w">err_tmp</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="w">POPs</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>is the direct equivalent of this bit of Perl</p>
944
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;Uh oh - $@\n&quot;</span> if <span class="i">$@</span><span class="sc">;</span></li></ol></pre><p><code class="inline"><span class="w">PL_errgv</span></code>
945
 is a perl global of type <code class="inline"><span class="w">GV</span> *</code>
946 947 948 949 950 951 952 953 954 955
 that points to the symbol
table entry containing the error.  <code class="inline"><span class="w">ERRSV</span></code>
 therefore refers to the C
equivalent of <code class="inline"><span class="i">$@</span></code>
.  We use a local temporary, <code class="inline"><span class="w">err_tmp</span></code>
, since
<code class="inline"><span class="w">ERRSV</span></code>
 is a macro that calls a function, and <code class="inline"><span class="i">SvTRUE</span><span class="s">(</span><span class="w">ERRSV</span><span class="s">)</span></code>
 would
end up calling that function multiple times.</p>
956 957
</dd>
<dt>3.</dt><dd>
958
<p>Note that the stack is popped using <code class="inline"><span class="w">POPs</span></code>
959
 in the block where
960
<code class="inline"><span class="i">SvTRUE</span><span class="s">(</span><span class="w">err_tmp</span><span class="s">)</span></code>
961 962 963 964
 is true.  This is necessary because whenever a
<i>call_*</i> function invoked with G_EVAL|G_SCALAR returns an error,
the top of the stack holds the value <i>undef</i>. Because we want the
program to continue after detecting this error, it is essential that
965 966 967
the stack be tidied up by removing the <i>undef</i>.</p>
</dd>
</dl>
968 969 970
<a name="Using-G_KEEPERR"></a><h2>Using G_KEEPERR</h2>
<p>Consider this rather facetious example, where we have used an XS
version of the call_Subtract example above inside a destructor:</p>
971
<pre class="verbatim"><ol><li><a name="package-Foo"></a>    package <span class="i">Foo</span><span class="sc">;</span></li><li><a name="new"></a>    sub <span class="m">new</span> <span class="s">{</span> <a class="l_k" href="functions/bless.html">bless</a> <span class="s">{</span><span class="s">}</span><span class="cm">,</span> <span class="i">$_</span>[<span class="n">0</span>] <span class="s">}</span></li><li><a name="Subtract"></a>    sub <span class="m">Subtract</span> <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a><span class="s">(</span><span class="i">$a</span><span class="cm">,</span><span class="i">$b</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;death can be fatal&quot;</span> if <span class="i">$a</span> &lt; <span class="i">$b</span><span class="sc">;</span></li><li>        <span class="i">$a</span> - <span class="i">$b</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li><a name="DESTROY"></a>    sub <span class="m">DESTROY</span> <span class="s">{</span> <span class="i">call_Subtract</span><span class="s">(</span><span class="n">5</span><span class="cm">,</span> <span class="n">4</span><span class="s">)</span><span class="sc">;</span> <span class="s">}</span></li><li><a name="foo"></a>    sub <span class="m">foo</span> <span class="s">{</span> <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;foo dies&quot;</span><span class="sc">;</span> <span class="s">}</span></li><li></li><li><a name="package-main"></a>    package <span class="i">main</span><span class="sc">;</span></li><li>    <span class="s">{</span></li><li>	<a class="l_k" href="functions/my.html">my</a> <span class="i">$foo</span> = <span class="w">Foo</span><span class="w">-&gt;new</span><span class="sc">;</span></li><li>	<a class="l_k" href="functions/eval.html">eval</a> <span class="s">{</span> <span class="i">$foo</span><span class="i">-&gt;foo</span> <span class="s">}</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li>    <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;Saw: $@&quot;</span> if <span class="i">$@</span><span class="sc">;</span>             <span class="c"># should be, but isn&#39;t</span></li></ol></pre><p>This example will fail to recognize that an error occurred inside the
972
<code class="inline"><a class="l_k" href="functions/eval.html">eval</a> <span class="s">{</span><span class="s">}</span></code>
973 974
.  Here's why: the call_Subtract code got executed while perl
was cleaning up temporaries when exiting the outer braced block, and because
975 976 977 978 979 980 981
call_Subtract is implemented with <i>call_pv</i> using the G_EVAL
flag, it promptly reset <code class="inline"><span class="i">$@</span></code>
.  This results in the failure of the
outermost test for <code class="inline"><span class="i">$@</span></code>
, and thereby the failure of the error trap.</p>
<p>Appending the G_KEEPERR flag, so that the <i>call_pv</i> call in
call_Subtract reads:</p>
982
<pre class="verbatim"><ol><li>        <span class="w">count</span> = <span class="i">call_pv</span><span class="s">(</span><span class="q">&quot;Subtract&quot;</span><span class="cm">,</span> <span class="w">G_EVAL</span>|<span class="w">G_SCALAR</span>|<span class="w">G_KEEPERR</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>will preserve the error and restore reliable error handling.</p>
983
<a name="Using-call_sv"></a><h2>Using call_sv</h2>
984
<p>In all the previous examples I have 'hard-wired' the name of the Perl
985 986
subroutine to be called from C.  Most of the time though, it is more
convenient to be able to specify the name of the Perl subroutine from
987 988
within the Perl script, and you'll want to use
<a href="perlapi.html#call_sv">call_sv</a>.</p>
989
<p>Consider the Perl code below</p>
990 991
<pre class="verbatim"><ol><li><a name="fred"></a>    sub <span class="m">fred</span></li><li>    <span class="s">{</span></li><li>        <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;Hello there\n&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li></li><li>    <span class="i">CallSubPV</span><span class="s">(</span><span class="q">&quot;fred&quot;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Here is a snippet of XSUB which defines <i>CallSubPV</i>.</p>
<pre class="verbatim"><ol><li>    void</li><li>    CallSubPV(name)</li><li>    	char *	name</li><li>    	CODE:</li><li>	PUSHMARK(SP);</li><li>	call_pv(name, G_DISCARD|G_NOARGS);</li></ol></pre><p>That is fine as far as it goes. The thing is, the Perl subroutine
992 993
can be specified as only a string, however, Perl allows references
to subroutines and anonymous subroutines.
994 995
This is where <i>call_sv</i> is useful.</p>
<p>The code below for <i>CallSubSV</i> is identical to <i>CallSubPV</i> except
996
that the <code class="inline"><span class="w">name</span></code>
997 998
 parameter is now defined as an SV* and we use
<i>call_sv</i> instead of <i>call_pv</i>.</p>
999
<pre class="verbatim"><ol><li>    void</li><li>    CallSubSV(name)</li><li>    	SV *	name</li><li>    	CODE:</li><li>	PUSHMARK(SP);</li><li>	call_sv(name, G_DISCARD|G_NOARGS);</li></ol></pre><p>Because we are using an SV to call <i>fred</i> the following can all be used:</p>
1000
<pre class="verbatim"><ol><li>    <span class="i">CallSubSV</span><span class="s">(</span><span class="q">&quot;fred&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">CallSubSV</span><span class="s">(</span>\<span class="i">&amp;fred</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">$ref</span> = \<span class="i">&amp;fred</span><span class="sc">;</span></li><li>    <span class="i">CallSubSV</span><span class="s">(</span><span class="i">$ref</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">CallSubSV</span><span class="s">(</span> <a class="l_k" href="functions/sub.html">sub</a> <span class="s">{</span> <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;Hello there\n&quot;</span> <span class="s">}</span> <span class="s">)</span><span class="sc">;</span></li></ol></pre><p>As you can see, <i>call_sv</i> gives you much greater flexibility in
1001
how you can specify the Perl subroutine.</p>
1002
<p>You should note that, if it is necessary to store the SV (<code class="inline"><span class="w">name</span></code>
1003 1004 1005
 in the
example above) which corresponds to the Perl subroutine so that it can
be used later in the program, it not enough just to store a copy of the
1006 1007
pointer to the SV. Say the code above had been like this:</p>
<pre class="verbatim"><ol><li>    static SV * rememberSub;</li><li></li><li>    void</li><li>    SaveSub1(name)</li><li>    	SV *	name</li><li>    	CODE:</li><li>	rememberSub = name;</li><li></li><li>    void</li><li>    CallSavedSub1()</li><li>    	CODE:</li><li>	PUSHMARK(SP);</li><li>	call_sv(rememberSub, G_DISCARD|G_NOARGS);</li></ol></pre><p>The reason this is wrong is that, by the time you come to use the
1008 1009
pointer <code class="inline"><span class="w">rememberSub</span></code>
 in <code class="inline"><span class="w">CallSavedSub1</span></code>
1010
, it may or may not still refer
1011
to the Perl subroutine that was recorded in <code class="inline"><span class="w">SaveSub1</span></code>
1012
.  This is
1013
particularly true for these cases:</p>
1014
<pre class="verbatim"><ol><li>    <span class="i">SaveSub1</span><span class="s">(</span>\<span class="i">&amp;fred</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">CallSavedSub1</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>    <span class="i">SaveSub1</span><span class="s">(</span> <a class="l_k" href="functions/sub.html">sub</a> <span class="s">{</span> <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;Hello there\n&quot;</span> <span class="s">}</span> <span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">CallSavedSub1</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>By the time each of the <code class="inline"><span class="w">SaveSub1</span></code>
1015
 statements above has been executed,
1016 1017
the SV*s which corresponded to the parameters will no longer exist.
Expect an error message from Perl of the form</p>
1018
<pre class="verbatim"><ol><li>    <span class="w">Can&#39;t</span> <a class="l_k" href="functions/use.html">use</a> <span class="w">an</span> <span class="w">undefined</span> <span class="w">value</span> <span class="w">as</span> <span class="w">a</span> <span class="w">subroutine</span> <span class="w">reference</span> <span class="w">at</span> ...</li></ol></pre><p>for each of the <code class="inline"><span class="w">CallSavedSub1</span></code>
1019 1020
 lines.</p>
<p>Similarly, with this code</p>
1021
<pre class="verbatim"><ol><li>    <span class="i">$ref</span> = \<span class="i">&amp;fred</span><span class="sc">;</span></li><li>    <span class="i">SaveSub1</span><span class="s">(</span><span class="i">$ref</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">$ref</span> = <span class="n">47</span><span class="sc">;</span></li><li>    <span class="i">CallSavedSub1</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>you can expect one of these messages (which you actually get is dependent on
1022
the version of Perl you are using)</p>
1023
<pre class="verbatim"><ol><li>    Not a CODE reference at ...</li><li>    Undefined subroutine &amp;main::47 called ...</li></ol></pre><p>The variable $ref may have referred to the subroutine <code class="inline"><span class="w">fred</span></code>
1024

1025
whenever the call to <code class="inline"><span class="w">SaveSub1</span></code>
1026
 was made but by the time
1027
<code class="inline"><span class="w">CallSavedSub1</span></code>
1028 1029
 gets called it now holds the number <code class="inline"><span class="n">47</span></code>
. Because we
1030
saved only a pointer to the original SV in <code class="inline"><span class="w">SaveSub1</span></code>
1031
, any changes to
1032
$ref will be tracked by the pointer <code class="inline"><span class="w">rememberSub</span></code>
1033
. This means that
1034
whenever <code class="inline"><span class="w">CallSavedSub1</span></code>
1035
 gets called, it will attempt to execute the
1036
code which is referenced by the SV* <code class="inline"><span class="w">rememberSub</span></code>
1037 1038 1039 1040
.  In this case
though, it now refers to the integer <code class="inline"><span class="n">47</span></code>
, so expect Perl to complain
loudly.</p>
1041
<p>A similar but more subtle problem is illustrated with this code:</p>
1042
<pre class="verbatim"><ol><li>    <span class="i">$ref</span> = \<span class="i">&amp;fred</span><span class="sc">;</span></li><li>    <span class="i">SaveSub1</span><span class="s">(</span><span class="i">$ref</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">$ref</span> = \<span class="i">&amp;joe</span><span class="sc">;</span></li><li>    <span class="i">CallSavedSub1</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>This time whenever <code class="inline"><span class="w">CallSavedSub1</span></code>
1043
 gets called it will execute the Perl
1044 1045
subroutine <code class="inline"><span class="w">joe</span></code>
 (assuming it exists) rather than <code class="inline"><span class="w">fred</span></code>
1046
 as was
1047
originally requested in the call to <code class="inline"><span class="w">SaveSub1</span></code>
1048 1049
.</p>
<p>To get around these problems it is necessary to take a full copy of the
1050
SV.  The code below shows <code class="inline"><span class="w">SaveSub2</span></code>
1051
 modified to do that.</p>
1052
<pre class="verbatim"><ol><li>    <span class="q">/* this isn&#39;t thread-safe */</span></li><li>    <span class="w">static</span> <span class="w">SV</span> * <span class="w">keepSub</span> = <span class="s">(</span><span class="w">SV</span>*<span class="s">)</span><span class="w">NULL</span><span class="sc">;</span></li><li></li><li>    <span class="w">void</span></li><li>    <span class="i">SaveSub2</span><span class="s">(</span><span class="w">name</span><span class="s">)</span></li><li>        <span class="w">SV</span> *	<span class="w">name</span></li><li>    	<span class="w">CODE</span><span class="co">:</span></li><li>     	<span class="q">/* Take a copy of the callback */</span></li><li>    	<a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="w">keepSub</span> == <span class="s">(</span><span class="w">SV</span>*<span class="s">)</span><span class="w">NULL</span><span class="s">)</span></li><li>    	    /<span class="i">* First</span> <a class="l_k" href="functions/time.html">time</a><span class="cm">,</span> <span class="w">so</span> <span class="w">create</span> <span class="w">a</span> <span class="w">new</span> <span class="w">SV</span> *<span class="q">/</span></li><li>	    <span class="q">	    keepSub = newSVsv(name);</span></li><li>    	<span class="q">    	else</span></li><li>    	    <span class="q">    	    /</span>* <span class="w">Been</span> <span class="w">here</span> <span class="w">before</span><span class="cm">,</span> <span class="w">so</span> <span class="w">overwrite</span> *<span class="q">/</span></li><li>	    <span class="q">	    SvSetSV(keepSub, name);</span></li><li></li><li>    <span class="q">    void</span></li><li>    <span class="q">    CallSavedSub2()</span></li><li>    	<span class="q">    	CODE:</span></li><li>	<span class="q">	PUSHMARK(SP);</span></li><li>	<span class="q">	call_sv(keepSub, G_DISCARD|G_NOARGS);</span></li></ol></pre><p>To avoid creating a new SV every time <code class="inline"><span class="w">SaveSub2</span></code>
1053 1054 1055
 is called,
the function first checks to see if it has been called before.  If not,
then space for a new SV is allocated and the reference to the Perl
1056
subroutine <code class="inline"><span class="w">name</span></code>
1057
 is copied to the variable <code class="inline"><span class="w">keepSub</span></code>
1058
 in one
1059 1060
operation using <code class="inline"><span class="w">newSVsv</span></code>
.  Thereafter, whenever <code class="inline"><span class="w">SaveSub2</span></code>
1061
 is called,
1062
the existing SV, <code class="inline"><span class="w">keepSub</span></code>
1063
, is overwritten with the new value using
1064
<code class="inline"><span class="w">SvSetSV</span></code>
1065
.</p>
1066 1067 1068 1069 1070
<p>Note: using a static or global variable to store the SV isn't
thread-safe.  You can either use the <code class="inline"><span class="w">MY_CXT</span></code>
 mechanism documented in
<a href="perlxs.html#Safely-Storing-Static-Data-in-XS">Safely Storing Static Data in XS in perlxs</a> which is fast, or store the
values in perl global variables, using get_sv(), which is much slower.</p>
1071 1072 1073
<a name="Using-call_argv"></a><h2>Using call_argv</h2>
<p>Here is a Perl subroutine which prints whatever parameters are passed
to it.</p>
1074
<pre class="verbatim"><ol><li><a name="PrintList"></a>    sub <span class="m">PrintList</span></li><li>    <span class="s">{</span></li><li>        <a class="l_k" href="functions/my.html">my</a><span class="s">(</span><span class="i">@list</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li></li><li>        foreach <span class="s">(</span><span class="i">@list</span><span class="s">)</span> <span class="s">{</span> <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;$_\n&quot;</span> <span class="s">}</span></li><li>    <span class="s">}</span></li></ol></pre><p>And here is an example of <i>call_argv</i> which will call
1075
<i>PrintList</i>.</p>
1076
<pre class="verbatim"><ol><li>    <span class="w">static</span> <span class="w">char</span> * <span class="w">words</span><span class="s">[</span><span class="s">]</span> = <span class="s">{</span><span class="q">&quot;alpha&quot;</span><span class="cm">,</span> <span class="q">&quot;beta&quot;</span><span class="cm">,</span> <span class="q">&quot;gamma&quot;</span><span class="cm">,</span> <span class="q">&quot;delta&quot;</span><span class="cm">,</span> <span class="w">NULL</span><span class="s">}</span><span class="sc">;</span></li><li></li><li>    <span class="w">static</span> <span class="w">void</span></li><li>    <span class="i">call_PrintList</span><span class="s">(</span><span class="s">)</span></li><li>    <span class="s">{</span></li><li>        <span class="i">call_argv</span><span class="s">(</span><span class="q">&quot;PrintList&quot;</span><span class="cm">,</span> <span class="w">G_DISCARD</span><span class="cm">,</span> <span class="w">words</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>Note that it is not necessary to call <code class="inline"><span class="w">PUSHMARK</span></code>
1077 1078 1079
 in this instance.
This is because <i>call_argv</i> will do it for you.</p>
<a name="Using-call_method"></a><h2>Using call_method</h2>
1080
<p>Consider the following Perl code:</p>
1081
<pre class="verbatim"><ol><li>    <span class="s">{</span></li><li><a name="package-Mine"></a>        package <span class="i">Mine</span><span class="sc">;</span></li><li></li><li><a name="new"></a>        sub <span class="m">new</span></li><li>        <span class="s">{</span></li><li>            <a class="l_k" href="functions/my.html">my</a><span class="s">(</span><span class="i">$type</span><span class="s">)</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span></li><li>            <a class="l_k" href="functions/bless.html">bless</a> <span class="s">[</span><span class="i">@_</span><span class="s">]</span></li><li>        <span class="s">}</span></li><li></li><li><a name="Display"></a>        sub <span class="m">Display</span></li><li>        <span class="s">{</span></li><li>            <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$self</span><span class="cm">,</span> <span class="i">$index</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>            <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;$index: $$self[$index]\n&quot;</span><span class="sc">;</span></li><li>        <span class="s">}</span></li><li></li><li><a name="PrintID"></a>        sub <span class="m">PrintID</span></li><li>        <span class="s">{</span></li><li>            <a class="l_k" href="functions/my.html">my</a><span class="s">(</span><span class="i">$class</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li>            <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;This is Class $class version 1.0\n&quot;</span><span class="sc">;</span></li><li>        <span class="s">}</span></li><li><a name="package-main"></a>    <span class="s">}</span></li></ol></pre><p>It implements just a very simple class to manage an array.  Apart from
1082
the constructor, <code class="inline"><span class="w">new</span></code>
1083
, it declares methods, one static and one
1084
virtual. The static method, <code class="inline"><span class="w">PrintID</span></code>
1085
, prints out simply the class
1086
name and a version number. The virtual method, <code class="inline"><span class="w">Display</span></code>
1087
, prints out a
1088
single element of the array.  Here is an all-Perl example of using it.</p>
1089 1090
<pre class="verbatim"><ol><li>    <span class="i">$a</span> = <span class="w">Mine</span><span class="w">-&gt;new</span><span class="s">(</span><span class="q">&#39;red&#39;</span><span class="cm">,</span> <span class="q">&#39;green&#39;</span><span class="cm">,</span> <span class="q">&#39;blue&#39;</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">$a</span><span class="i">-&gt;Display</span><span class="s">(</span><span class="n">1</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="w">Mine</span><span class="w">-&gt;PrintID</span><span class="sc">;</span></li></ol></pre><p>will print</p>
<pre class="verbatim"><ol><li>    1: green</li><li>    This is Class Mine version 1.0</li></ol></pre><p>Calling a Perl method from C is fairly straightforward. The following
1091
things are required:</p>
1092 1093
<ul>
<li>
1094 1095
<p>A reference to the object for a virtual method or the name of the class
for a static method</p>
1096 1097
</li>
<li>
1098
<p>The name of the method</p>
1099 1100
</li>
<li>
1101
<p>Any other parameters specific to the method</p>
1102 1103 1104
</li>
</ul>
<p>Here is a simple XSUB which illustrates the mechanics of calling both
1105 1106
the <code class="inline"><span class="w">PrintID</span></code>
 and <code class="inline"><span class="w">Display</span></code>
1107
 methods from C.</p>
1108
<pre class="verbatim"><ol><li>    <span class="w">void</span></li><li>    <span class="i">call_Method</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="cm">,</span> <span class="w">method</span><span class="cm">,</span> <a class="l_k" href="functions/index.html">index</a><span class="s">)</span></li><li>        <span class="w">SV</span> *	<a class="l_k" href="functions/ref.html">ref</a></li><li>        <span class="w">char</span> *	<span class="w">method</span></li><li>        <a class="l_k" href="functions/int.html">int</a>		<a class="l_k" href="functions/index.html">index</a></li><li>        <span class="w">CODE</span><span class="co">:</span></li><li>        <span class="i">PUSHMARK</span><span class="s">(</span><span class="w">SP</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">EXTEND</span><span class="s">(</span><span class="w">SP</span><span class="cm">,</span> <span class="n">2</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">PUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSViv</span><span class="s">(</span><a class="l_k" href="functions/index.html">index</a><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="w">PUTBACK</span><span class="sc">;</span></li><li></li><li>        <span class="i">call_method</span><span class="s">(</span><span class="w">method</span><span class="cm">,</span> <span class="w">G_DISCARD</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>    <span class="w">void</span></li><li>    <span class="i">call_PrintID</span><span class="s">(</span><span class="w">class</span><span class="cm">,</span> <span class="w">method</span><span class="s">)</span></li><li>        <span class="w">char</span> *	<span class="w">class</span></li><li>        <span class="w">char</span> *	<span class="w">method</span></li><li>        <span class="w">CODE</span><span class="co">:</span></li><li>        <span class="i">PUSHMARK</span><span class="s">(</span><span class="w">SP</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="i">XPUSHs</span><span class="s">(</span><span class="i">sv_2mortal</span><span class="s">(</span><span class="i">newSVpv</span><span class="s">(</span><span class="w">class</span><span class="cm">,</span> <span class="n">0</span><span class="s">)</span><span class="s">)</span><span class="s">)</span><span class="sc">;</span></li><li>        <span class="w">PUTBACK</span><span class="sc">;</span></li><li></li><li>        <span class="i">call_method</span><span class="s">(</span><span class="w">method</span><span class="cm">,</span> <span class="w">G_DISCARD</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>So the methods <code class="inline"><span class="w">PrintID</span></code>
1109
 and <code class="inline"><span class="w">Display</span></code>
1110 1111
 can be invoked like this:</p>
<pre class="verbatim"><ol><li>    <span class="i">$a</span> = <span class="w">Mine</span><span class="w">-&gt;new</span><span class="s">(</span><span class="q">&#39;red&#39;</span><span class="cm">,</span> <span class="q">&#39;green&#39;</span><span class="cm">,</span> <span class="q">&#39;blue&#39;</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">call_Method</span><span class="s">(</span><span class="i">$a</span><span class="cm">,</span> <span class="q">&#39;Display&#39;</span><span class="cm">,</span> <span class="n">1</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">call_PrintID</span><span class="s">(</span><span class="q">&#39;Mine&#39;</span><span class="cm">,</span> <span class="q">&#39;PrintID&#39;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The only thing to note is that, in both the static and virtual methods,
1112 1113 1114 1115 1116
the method name is not passed via the stack--it is used as the first
parameter to <i>call_method</i>.</p>
<a name="Using-GIMME_V"></a><h2>Using GIMME_V</h2>
<p>Here is a trivial XSUB which prints the context in which it is
currently executing.</p>
1117
<pre class="verbatim"><ol><li>    <span class="w">void</span></li><li>    <span class="i">PrintContext</span><span class="s">(</span><span class="s">)</span></li><li>        <span class="w">CODE</span><span class="co">:</span></li><li>        <span class="w">U8</span> <span class="w">gimme</span> = <span class="w">GIMME_V</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="w">gimme</span> == <span class="w">G_VOID</span><span class="s">)</span></li><li>            <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;Context is Void\n&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/else.html">else</a> <a class="l_k" href="functions/if.html">if</a> <span class="s">(</span><span class="w">gimme</span> == <span class="w">G_SCALAR</span><span class="s">)</span></li><li>            <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;Context is Scalar\n&quot;</span><span class="s">)</span><span class="sc">;</span></li><li>        <a class="l_k" href="functions/else.html">else</a></li><li>            <a class="l_k" href="functions/printf.html">printf</a> <span class="s">(</span><span class="q">&quot;Context is Array\n&quot;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>And here is some Perl to test it.</p>
1118
<pre class="verbatim"><ol><li>    <span class="w">PrintContext</span><span class="sc">;</span></li><li>    <span class="i">$a</span> = <span class="w">PrintContext</span><span class="sc">;</span></li><li>    <span class="i">@a</span> = <span class="w">PrintContext</span><span class="sc">;</span></li></ol></pre><p>The output from that will be</p>
1119
<pre class="verbatim"><ol><li>    <span class="w">Context</span> <span class="w">is</span> <span class="w">Void</span></li><li>    <span class="w">Context</span> <span class="w">is</span> <span class="w">Scalar</span></li><li>    <span class="w">Context</span> <span class="w">is</span> <span class="w">Array</span></li></ol></pre><a name="Using-Perl-to-Dispose-of-Temporaries"></a><h2>Using Perl to Dispose of Temporaries</h2>
1120 1121
<p>In the examples given to date, any temporaries created in the callback
(i.e., parameters passed on the stack to the <i>call_*</i> function or
1122
values returned via the stack) have been freed by one of these methods:</p>
1123 1124
<ul>
<li>
1125
<p>Specifying the G_DISCARD flag with <i>call_*</i></p>