-
Notifications
You must be signed in to change notification settings - Fork 2
/
perlcall.html
1432 lines (1303 loc) · 159 KB
/
perlcall.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
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
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
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
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
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
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="perlcall - perldoc.perl.org">
<link rel="icon" href="/public/img/favicon.ico">
<title>perlcall - perldoc.perl.org</title>
<link href="/public/css/main.min.css" rel="stylesheet">
<link rel="canonical" href="/perlcall.html">
<link href='https://fonts.googleapis.com/css?family=Lato:400,100,300,700,900' rel='stylesheet' type='text/css'>
<script>
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-1892152-2', 'auto'); // JJ's account
ga('create', 'UA-50555-3', 'auto', 'perlOrg'); // perl.org account
ga('require', 'outboundLinkTracker', {
events: ['click', 'auxclick', 'contextmenu'],
});
ga('require', 'maxScrollTracker');
ga('send', 'pageview');
ga('perlOrg.send', 'pageview');
</script>
<script async src="https://www.google-analytics.com/analytics.js"></script>
<script async src="/public/js/tracking.min.js"></script>
</head>
<body class="body container-fluid ">
<div class="wrapper">
<nav class="navbar navbar-expand-md navbar-dark bg-primary bg-perl fixed-top justify-content-between">
<a class="navbar-brand" href="/">
<object class="logo" data="/public/img/logo_perl_doc.svg" type="image/svg+xml" name="Perl Documentation Logo">Perl Documentation Logo</object>
</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div id="navbar" class="collapse navbar-collapse justify-content-end">
<ul class="nav navbar-nav navbar-right">
<li class="nav-item dropdown">
<a id="navbarDropdown" href="#" class="nav-link dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Perl versions</a>
<div class="dropdown-menu" id="dropdown-menu-links" aria-labelledby="navbarDropdown">
<p class='dropdown-item major-version'>
5.28
</p>
<a class='dropdown-item minor-version' href="/5.28.2">5.28.2</a>
<a class='dropdown-item minor-version' href="/5.28.1">5.28.1</a>
<a class='dropdown-item minor-version' href="/5.28.0">5.28.0</a>
<div class="dropdown-divider"></div>
<p class='dropdown-item major-version'>
5.26
</p>
<a class='dropdown-item minor-version' href="/5.26.3">5.26.3</a>
<a class='dropdown-item minor-version' href="/5.26.2">5.26.2</a>
<a class='dropdown-item minor-version' href="/5.26.1">5.26.1</a>
<a class='dropdown-item minor-version' href="/5.26.0">5.26.0</a>
<div class="dropdown-divider"></div>
<p class='dropdown-item major-version'>
5.24
</p>
<a class='dropdown-item minor-version' href="/5.24.4">5.24.4</a>
<a class='dropdown-item minor-version' href="/5.24.3">5.24.3</a>
<a class='dropdown-item minor-version' href="/5.24.2">5.24.2</a>
<a class='dropdown-item minor-version' href="/5.24.1">5.24.1</a>
<a class='dropdown-item minor-version' href="/5.24.0">5.24.0</a>
<div class="dropdown-divider"></div>
<p class='dropdown-item major-version'>
5.22
</p>
<a class='dropdown-item minor-version' href="/5.22.3">5.22.3</a>
<a class='dropdown-item minor-version' href="/5.22.2">5.22.2</a>
<a class='dropdown-item minor-version' href="/5.22.1">5.22.1</a>
<a class='dropdown-item minor-version' href="/5.22.0">5.22.0</a>
<div class="dropdown-divider"></div>
<p class='dropdown-item major-version'>
5.20
</p>
<a class='dropdown-item minor-version' href="/5.20.3">5.20.3</a>
<a class='dropdown-item minor-version' href="/5.20.2">5.20.2</a>
<a class='dropdown-item minor-version' href="/5.20.1">5.20.1</a>
<a class='dropdown-item minor-version' href="/5.20.0">5.20.0</a>
<div class="dropdown-divider"></div>
<p class='dropdown-item major-version'>
5.18
</p>
<a class='dropdown-item minor-version' href="/5.18.4">5.18.4</a>
<a class='dropdown-item minor-version' href="/5.18.3">5.18.3</a>
<a class='dropdown-item minor-version' href="/5.18.2">5.18.2</a>
<a class='dropdown-item minor-version' href="/5.18.1">5.18.1</a>
<a class='dropdown-item minor-version' href="/5.18.0">5.18.0</a>
<div class="dropdown-divider"></div>
<p class='dropdown-item major-version'>
5.16
</p>
<a class='dropdown-item minor-version' href="/5.16.3">5.16.3</a>
<a class='dropdown-item minor-version' href="/5.16.2">5.16.2</a>
<a class='dropdown-item minor-version' href="/5.16.1">5.16.1</a>
<a class='dropdown-item minor-version' href="/5.16.0">5.16.0</a>
<div class="dropdown-divider"></div>
<p class='dropdown-item major-version'>
5.14
</p>
<a class='dropdown-item minor-version' href="/5.14.4">5.14.4</a>
<a class='dropdown-item minor-version' href="/5.14.3">5.14.3</a>
<a class='dropdown-item minor-version' href="/5.14.2">5.14.2</a>
<a class='dropdown-item minor-version' href="/5.14.1">5.14.1</a>
<a class='dropdown-item minor-version' href="/5.14.0">5.14.0</a>
<div class="dropdown-divider"></div>
<p class='dropdown-item major-version'>
5.12
</p>
<a class='dropdown-item minor-version' href="/5.12.5">5.12.5</a>
<a class='dropdown-item minor-version' href="/5.12.4">5.12.4</a>
<a class='dropdown-item minor-version' href="/5.12.3">5.12.3</a>
<a class='dropdown-item minor-version' href="/5.12.2">5.12.2</a>
<a class='dropdown-item minor-version' href="/5.12.1">5.12.1</a>
<a class='dropdown-item minor-version' href="/5.12.0">5.12.0</a>
<div class="dropdown-divider"></div>
<p class='dropdown-item major-version'>
5.10
</p>
<a class='dropdown-item minor-version' href="/5.10.1">5.10.1</a>
<a class='dropdown-item minor-version' href="/5.10.0">5.10.0</a>
<div class="dropdown-divider"></div>
<p class='dropdown-item major-version'>
5.8
</p>
<a class='dropdown-item minor-version' href="/5.8.9">5.8.9</a>
<a class='dropdown-item minor-version' href="/5.8.8">5.8.8</a>
<a class='dropdown-item minor-version' href="/5.8.7">5.8.7</a>
<a class='dropdown-item minor-version' href="/5.8.6">5.8.6</a>
<a class='dropdown-item minor-version' href="/5.8.5">5.8.5</a>
<a class='dropdown-item minor-version' href="/5.8.4">5.8.4</a>
<a class='dropdown-item minor-version' href="/5.8.3">5.8.3</a>
<a class='dropdown-item minor-version' href="/5.8.2">5.8.2</a>
<a class='dropdown-item minor-version' href="/5.8.1">5.8.1</a>
<a class='dropdown-item minor-version' href="/5.8.0">5.8.0</a>
<div class="dropdown-divider"></div>
<p class='dropdown-item major-version'>
5.6
</p>
<a class='dropdown-item minor-version' href="/5.6.2">5.6.2</a>
<a class='dropdown-item minor-version' href="/5.6.1">5.6.1</a>
<a class='dropdown-item minor-version' href="/5.6.0">5.6.0</a>
</div>
</li>
<li class="nav-item dropdown">
<a id="navbarDropdown1" href="#" class="dropdown-toggle nav-link" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Manuals</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdown1">
<a class="dropdown-item" href="/5.28.2/index-overview.html">Overview</a>
<a class="dropdown-item" href="/5.28.2/index-tutorials.html">Tutorials</a>
<a class="dropdown-item" href="/5.28.2/index-faq.html">FAQs</a>
<a class="dropdown-item" href="/5.28.2/index-history.html">History / Changes</a>
<a class="dropdown-item" href="/5.28.2/index-licence.html">License</a>
<a class="dropdown-item" href="/5.28.2/index-language.html">Language</a>
<a class="dropdown-item" href="/5.28.2/index-functions.html">Functions</a>
<a class="dropdown-item" href="/5.28.2/perlop.html">Operators</a>
<a class="dropdown-item" href="/5.28.2/perlvar.html">Special Variables</a>
<a class="dropdown-item" href="/5.28.2/index-pragmas.html">Pragmas</a>
<a class="dropdown-item" href="/5.28.2/index-utilities.html">Utilities</a>
<a class="dropdown-item" href="/5.28.2/index-internals.html">Internals</a>
<a class="dropdown-item" href="/5.28.2/index-platforms.html">Platform Specific</a>
</div>
</li>
<li class="nav-item dropdown">
<a id="navbarDropdown3" href="#" class="nav-link dropdown-toggle " data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Modules</a>
<div aria-labelledby="navbarDropdown3" class="dropdown-menu letters-wrap">
<a class="dropdown-item" href="/5.28.2/index-functions.html">A-Z</a>
<a class="dropdown-item" href="/5.28.2/index-functions-by-cat.html">By Category</a>
<div class="dropdown-divider"></div>
<div class="letter-container">
<a class="dropdown-item letters" href="/5.28.2/index-modules-A.html">A</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-B.html">B</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-C.html">C</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-D.html">D</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-E.html">E</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-F.html">F</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-G.html">G</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-H.html">H</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-I.html">I</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-J.html">J</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-L.html">L</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-M.html">M</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-N.html">N</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-O.html">O</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-P.html">P</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-S.html">S</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-T.html">T</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-U.html">U</a>
<a class="dropdown-item letters" href="/5.28.2/index-modules-X.html">X</a>
</div>
</div>
</li>
</ul>
</div>
<!--/.nav-collapse -->
</nav>
<main class="row main-content pb-5 pt-5">
<div class="col-sm-8 offset-sm-2">
<div class="row">
<div class="col-sm-12">
<div id="breadcrumbs">
<a href="index.html">Home</a> >
<a href="index-internals.html">Internals and C language interface</a> >
perlcall
</div>
</div>
</div>
<div class="row">
<article class="col-sm-12 content">
<div class="documentation-wrapper">
<div id="perl_version">
<h1 class='page-title'> Perl 5 version documentation</h1>
</div>
<h1>perlcall</h1>
<!-- -->
<ul><li><a href="#NAME">NAME</a></li><li><a href="#DESCRIPTION">DESCRIPTION</a></li><li><a href="#THE-CALL_-FUNCTIONS">THE CALL_ FUNCTIONS</a></li><li><a href="#FLAG-VALUES">FLAG VALUES</a></li><ul><li><a href="#G_VOID">G_VOID</a></li><li><a href="#G_SCALAR">G_SCALAR</a></li><li><a href="#G_ARRAY">G_ARRAY</a></li><li><a href="#G_DISCARD">G_DISCARD</a></li><li><a href="#G_NOARGS">G_NOARGS</a></li><li><a href="#G_EVAL">G_EVAL</a></li><li><a href="#G_KEEPERR">G_KEEPERR</a></li><li><a href="#Determining-the-Context">Determining the Context</a></li></ul><li><a href="#EXAMPLES">EXAMPLES</a></li><ul><li><a href="#No-Parameters%2c-Nothing-Returned">No Parameters, Nothing Returned</a></li><li><a href="#Passing-Parameters">Passing Parameters</a></li><li><a href="#Returning-a-Scalar">Returning a Scalar</a></li><li><a href="#Returning-a-List-of-Values">Returning a List of Values</a></li><li><a href="#Returning-a-List-in-a-Scalar-Context">Returning a List in a Scalar Context</a></li><li><a href="#Returning-Data-from-Perl-via-the-Parameter-List">Returning Data from Perl via the Parameter List</a></li><li><a href="#Using-G_EVAL">Using G_EVAL</a></li><li><a href="#Using-G_KEEPERR">Using G_KEEPERR</a></li><li><a href="#Using-call_sv">Using call_sv</a></li><li><a href="#Using-call_argv">Using call_argv</a></li><li><a href="#Using-call_method">Using call_method</a></li><li><a href="#Using-GIMME_V">Using GIMME_V</a></li><li><a href="#Using-Perl-to-Dispose-of-Temporaries">Using Perl to Dispose of Temporaries</a></li><li><a href="#Strategies-for-Storing-Callback-Context-Information">Strategies for Storing Callback Context Information</a></li><li><a href="#Alternate-Stack-Manipulation">Alternate Stack Manipulation</a></li><li><a href="#Creating-and-Calling-an-Anonymous-Subroutine-in-C">Creating and Calling an Anonymous Subroutine in C</a></li></ul><li><a href="#LIGHTWEIGHT-CALLBACKS">LIGHTWEIGHT CALLBACKS</a></li><li><a href="#SEE-ALSO">SEE ALSO</a></li><li><a href="#AUTHOR">AUTHOR</a></li><li><a href="#DATE">DATE</a></li></ul><a id="NAME"></a><h2 class='h2' >NAME</h2>
<p>perlcall - Perl calling conventions from C</p>
<a id="DESCRIPTION"></a><h2 class='h2' >DESCRIPTION</h2>
<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 id="*-An-Error-Handler"></a><strong>An Error Handler</strong>
<p>You have created an XSUB interface to an application's C API.</p>
<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>
<li><a id="*-An-Event-Driven-Program"></a><strong>An Event-Driven Program</strong>
<p>The classic example of where callbacks are used is when writing an
event driven program, such as for an X11 application. In this case
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,
it would be a good idea to have read the following two documents--<a href="https://search.cpan.org/perldoc/perlxs">perlxs</a>
and <a href="perlguts.html">perlguts</a>.</p>
<a id="THE-CALL_-FUNCTIONS"></a><h2 class='h2' >THE CALL_ FUNCTIONS</h2>
<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>
<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
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>
<p>All the <i>call_*</i> functions have a <code class="inline"><span class="w">flags</span></code>
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
bit mask are discussed in <a href="#FLAG-VALUES">FLAG VALUES</a>.</p>
<p>Each of the functions will now be discussed in turn.</p>
<ul>
<li><a id="call_sv"></a><strong>call_sv</strong>
<p><i>call_sv</i> takes two parameters. The first, <code class="inline"><span class="w">sv</span></code>
, 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
subroutine. The section, <i>Using call_sv</i>, shows how you can make
use of <i>call_sv</i>.</p>
</li>
<li><a id="call_pv"></a><strong>call_pv</strong>
<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">"fred"</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">"pkg::fred"</span></code>
.</p>
</li>
<li><a id="call_method"></a><strong>call_method</strong>
<p>The function <i>call_method</i> is used to call a method from a Perl
class. The parameter <code class="inline"><span class="w">methname</span></code>
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
static and virtual methods and <a href="#Using-call_method">Using call_method</a> for an example
of using <i>call_method</i>.</p>
</li>
<li><a id="call_argv"></a><strong>call_argv</strong>
<p><i>call_argv</i> calls the Perl subroutine specified by the C string
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>
parameter. The final parameter, <code class="inline"><span class="w">argv</span></code>
, consists of a NULL-terminated
list of C strings to be passed as parameters to the Perl subroutine.
See <i>Using call_argv</i>.</p>
</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
stop someone from doing something unexpected--don't say you haven't
been warned.</p>
<a id="FLAG-VALUES"></a><h2 class='h2' >FLAG VALUES</h2>
<p>The <code class="inline"><span class="w">flags</span></code>
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>
<a id="G_VOID"></a><h3 class='h3' >G_VOID</h3>
<p>Calls the Perl subroutine in a void context.</p>
<p>This flag has 2 effects:</p>
<dl>
<dt>1.</dt><dd>
<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>
</dd>
<dt>2.</dt><dd>
<p>It ensures that nothing is actually returned from the subroutine.</p>
</dd>
</dl>
<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 0.</p>
<a id="G_SCALAR"></a><h3 class='h3' >G_SCALAR</h3>
<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>
<dl>
<dt>1.</dt><dd>
<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>
</dd>
<dt>2.</dt><dd>
<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>
</dd>
</dl>
<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
stored on the Perl stack - the section <i>Returning a Scalar</i> shows how
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
<i>call_*</i> function. The section <i>Returning a list in a scalar
context</i> shows an example of this behavior.</p>
<a id="G_ARRAY"></a><h3 class='h3' >G_ARRAY</h3>
<p>Calls the Perl subroutine in a list context.</p>
<p>As with G_SCALAR, this flag has 2 effects:</p>
<dl>
<dt>1.</dt><dd>
<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>
</dd>
<dt>2.</dt><dd>
<p>It ensures that all items returned from the subroutine will be
accessible when control returns from the <i>call_*</i> function.</p>
</dd>
</dl>
<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
section <i>Returning a list of values</i> gives an example of using the
G_ARRAY flag and the mechanics of accessing the returned items from the
Perl stack.</p>
<a id="G_DISCARD"></a><h3 class='h3' >G_DISCARD</h3>
<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
yourself. The section <i>Returning a Scalar</i> gives details of how to
dispose of these temporaries explicitly and the section <i>Using Perl to
dispose of temporaries</i> discusses the specific circumstances where you
can ignore the problem and let Perl deal with it for you.</p>
<a id="G_NOARGS"></a><h3 class='h3' >G_NOARGS</h3>
<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
so. The reason for being cautious is that, even if you have specified
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>
<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">"@_\n"</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">&fred</span> <span class="s">}</span></li><li></li><li> <span class="i">&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> <span class="n">1</span> <span class="n">2</span> <span class="n">3</span></li></ol></pre><p>What has happened is that <code class="inline"><span class="w">fred</span></code>
accesses the <code class="inline"><span class="i">@_</span></code>
array which
belongs to <code class="inline"><span class="w">joe</span></code>
.</p>
<a id="G_EVAL"></a><h3 class='h3' >G_EVAL</h3>
<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>
<p>See <i>Using G_EVAL</i> for details on using G_EVAL.</p>
<a id="G_KEEPERR"></a><h3 class='h3' >G_KEEPERR</h3>
<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>
or <code class="inline"><span class="w">__WARN__</span></code>
hooks, and <code class="inline"><a class="l_k" href="functions/tie.html">tie</a></code> functions.</p>
<p>The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
<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">'misc'</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>
.</p>
<p>The G_KEEPERR flag was introduced in Perl version 5.002.</p>
<p>See <i>Using G_KEEPERR</i> for an example of a situation that warrants the
use of this flag.</p>
<a id="Determining-the-Context"></a><h3 class='h3' >Determining the Context</h3>
<p>As mentioned above, you can determine the context of the currently
executing subroutine in Perl with <i>wantarray</i>. The equivalent test
can be made in C by using the <code class="inline"><span class="w">GIMME_V</span></code>
macro, which returns
<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>
if
in a scalar context, or <code class="inline"><span class="w">G_VOID</span></code>
if in a void context (i.e., the
return value will not be used). An older version of this macro is
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>
instead of
<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>
macro is shown in
section <i>Using GIMME_V</i>.</p>
<a id="EXAMPLES"></a><h2 class='h2' >EXAMPLES</h2>
<p>Enough of the definition talk! Let's have a few examples.</p>
<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
<i>Using call_sv</i> for details.</p>
<a id="No-Parameters%2c-Nothing-Returned"></a><h3 class='h3' >No Parameters, Nothing Returned</h3>
<p>This first trivial example will call a Perl subroutine, <i>PrintUID</i>, to
print out the UID of the process.</p>
<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">"UID is $<\n"</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>
<pre class="verbatim"><ol><li> <span class="w">static</span> <span class="w">void</span></li><li> <span class="i">call_PrintUID</span><span class="s">(</span><span class="s">)</span></li><li> <span class="s">{</span></li><li> <span class="w">dSP</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">call_pv</span><span class="s">(</span><span class="q">"PrintUID"</span><span class="cm">,</span> <span class="w">G_DISCARD</span>|<span class="w">G_NOARGS</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="s">}</span></li></ol></pre><p>Simple, eh?</p>
<p>A few points to note about this example:</p>
<dl>
<dt>1.</dt><dd>
<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>
for now. They will be discussed in
the next example.</p>
</dd>
<dt>2.</dt><dd>
<p>We aren't passing any parameters to <i>PrintUID</i> so G_NOARGS can be
specified.</p>
</dd>
<dt>3.</dt><dd>
<p>We aren't interested in anything returned from <i>PrintUID</i>, so
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>
</dd>
<dt>4.</dt><dd>
<p>As <i>call_pv</i> is being used, the Perl subroutine is specified as a
C string. In this case the subroutine name has been 'hard-wired' into the
code.</p>
</dd>
<dt>5.</dt><dd>
<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>
</dd>
</dl>
<a id="Passing-Parameters"></a><h3 class='h3' >Passing Parameters</h3>
<p>Now let's make a slightly more complex example. This time we want to
call a Perl subroutine, <code class="inline"><span class="w">LeftString</span></code>
, 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>
<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">"\n"</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>
<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">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">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">XPUSHs</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">"LeftString"</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>
<dl>
<dt>1.</dt><dd>
<p>Parameters are passed to the Perl subroutine using the Perl stack.
This is the purpose of the code beginning with the line <code class="inline"><span class="w">dSP</span></code>
and
ending with the line <code class="inline"><span class="w">PUTBACK</span></code>
. The <code class="inline"><span class="w">dSP</span></code>
declares a local copy
of the stack pointer. This local copy should <strong>always</strong> be accessed
as <code class="inline"><span class="w">SP</span></code>
.</p>
</dd>
<dt>2.</dt><dd>
<p>If you are going to put something onto the Perl stack, you need to know
where to put it. This is the purpose of the macro <code class="inline"><span class="w">dSP</span></code>
--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
use the <code class="inline"><span class="w">dSP</span></code>
macro explicitly--it will be declared for you
automatically.</p>
</dd>
<dt>3.</dt><dd>
<p>Any parameters to be pushed onto the stack should be bracketed by the
<code class="inline"><span class="w">PUSHMARK</span></code>
and <code class="inline"><span class="w">PUTBACK</span></code>
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>
<p>The <code class="inline"><span class="w">PUSHMARK</span></code>
macro tells Perl to make a mental note of the current
stack pointer. Even if you aren't passing any parameters (like the
example shown in the section <i>No Parameters, Nothing Returned</i>) you
must still call the <code class="inline"><span class="w">PUSHMARK</span></code>
macro before you can call any of the
<i>call_*</i> functions--Perl still needs to know that there are no
parameters.</p>
<p>The <code class="inline"><span class="w">PUTBACK</span></code>
macro sets the global copy of the stack pointer to be
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
up to now all the stack pointer manipulation we have done is with our
local copy, <i>not</i> the global copy.</p>
</dd>
<dt>4.</dt><dd>
<p>Next, we come to XPUSHs. This is where the parameters actually get
pushed onto the stack. In this case we are pushing a string and an
integer.</p>
<p>See <a href="perlguts.html#XSUBs-and-the-Argument-Stack">XSUBs and the Argument Stack in perlguts</a> for details
on how the XPUSH macros work.</p>
</dd>
<dt>5.</dt><dd>
<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>
<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>
/<code class="inline"><span class="w">SAVETMPS</span></code>
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>
<p>The <code class="inline"><span class="w">FREETMPS</span></code>
/<code class="inline"><span class="w">LEAVE</span></code>
pair will get rid of any values returned by
the Perl subroutine (see next example), plus it will also dump the
mortal SVs we have created. Having <code class="inline"><span class="w">ENTER</span></code>
/<code class="inline"><span class="w">SAVETMPS</span></code>
at the
beginning of the code makes sure that no other mortals are destroyed.</p>
<p>Think of these macros as working a bit like <code class="inline"><span class="s">{</span></code>
and <code class="inline"><span class="s">}</span></code>
in Perl
to limit the scope of local variables.</p>
<p>See the section <i>Using Perl to Dispose of Temporaries</i> for details of
an alternative to using these macros.</p>
</dd>
<dt>6.</dt><dd>
<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>
</dd>
</dl>
<a id="Returning-a-Scalar"></a><h3 class='h3' >Returning a Scalar</h3>
<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>
<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
function required to call it is now a bit more complex.</p>
<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">XPUSHs</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">XPUSHs</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">"Adder"</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">"Big trouble\n"</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">"The sum of %d and %d is %d\n"</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>
<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>
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>
</dd>
<dt>2.</dt><dd>
<p>The purpose of the macro <code class="inline"><span class="w">SPAGAIN</span></code>
is to refresh the local copy of the
stack pointer. This is necessary because it is possible that the memory
allocated to the Perl stack has been reallocated during the
<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>
</dd>
<dt>3.</dt><dd>
<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
didn't check for that possibility and take appropriate action the Perl
stack would end up in an inconsistent state. That is something you
<i>really</i> don't want to happen ever.</p>
</dd>
<dt>4.</dt><dd>
<p>The <code class="inline"><span class="w">POPi</span></code>
macro is used here to pop the return value from the stack.
In this case we wanted an integer, so <code class="inline"><span class="w">POPi</span></code>
was used.</p>
<p>Here is the complete list of POP macros available, along with the types
they return.</p>
<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></li><li> <span class="w">POPn</span> <span class="w">double</span></li><li> <span class="w">POPi</span> <span class="w">integer</span></li><li> <span class="w">POPl</span> <span class="w">long</span></li></ol></pre></dd>
<dt>5.</dt><dd>
<p>The final <code class="inline"><span class="w">PUTBACK</span></code>
is used to leave the Perl stack in a consistent
state before exiting the function. This is necessary because when we
popped the return value from the stack with <code class="inline"><span class="w">POPi</span></code>
it updated only our
local copy of the stack pointer. Remember, <code class="inline"><span class="w">PUTBACK</span></code>
sets the global
stack pointer to be the same as our local copy.</p>
</dd>
</dl>
<a id="Returning-a-List-of-Values"></a><h3 class='h3' >Returning a List of Values</h3>
<p>Now, let's extend the previous example to return both the sum of the
parameters and the difference.</p>
<p>Here is the Perl subroutine</p>
<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>
<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">XPUSHs</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">XPUSHs</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">"AddSubtract"</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">"Big trouble\n"</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">"%d - %d = %d\n"</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">"%d + %d = %d\n"</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>
<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> <span class="n">7</span> - <span class="n">4</span> = <span class="n">3</span></li><li> <span class="n">7</span> + <span class="n">4</span> = <span class="n">11</span></li></ol></pre><p>Notes</p>
<dl>
<dt>1.</dt><dd>
<p>We wanted list context, so G_ARRAY was used.</p>
</dd>
<dt>2.</dt><dd>
<p>Not surprisingly <code class="inline"><span class="w">POPi</span></code>
is used twice this time because we were
retrieving 2 values from the stack. The important thing to note is that
when using the <code class="inline"><span class="w">POP</span>*</code>
macros they come off the stack in <i>reverse</i>
order.</p>
</dd>
</dl>
<a id="Returning-a-List-in-a-Scalar-Context"></a><h3 class='h3' >Returning a List in a Scalar Context</h3>
<p>Say the Perl subroutine in the previous section was called in a scalar
context, like this</p>
<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">XPUSHs</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">XPUSHs</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">"AddSubtract"</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">"Items Returned = %d\n"</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> <= <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">"Value %d = %d\n"</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
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>
<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> <span class="w">Items</span> <span class="w">Returned</span> = <span class="n">1</span></li><li> <span class="w">Value</span> <span class="n">1</span> = <span class="n">3</span></li></ol></pre><p>In this case the main point to note is that only the last item in the
list is returned from the subroutine. <i>AddSubtract</i> actually made it back to
<i>call_AddSubScalar</i>.</p>
<a id="Returning-Data-from-Perl-via-the-Parameter-List"></a><h3 class='h3' >Returning Data from Perl via the Parameter List</h3>
<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>
<p>The Perl subroutine, <i>Inc</i>, below takes 2 parameters and increments
each directly.</p>
<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>
<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">XPUSHs</span><span class="s">(</span><span class="w">sva</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">XPUSHs</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">"Inc"</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">"call_Inc: expected 0 values from 'Inc', got %d\n"</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">"%d + 1 = %d\n"</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">"%d + 1 = %d\n"</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
after they return from <i>call_pv</i> it is necessary to make a note
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>
.</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 id="Using-G_EVAL"></a><h3 class='h3' >Using G_EVAL</h3>
<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>
<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">"death can be fatal\n"</span> <a class="l_k" href="functions/if.html">if</a> <span class="i">$a</span> < <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>
<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></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">XPUSHs</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">XPUSHs</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">"Subtract"</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> <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">ERRSV</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">"Uh oh - %s\n"</span><span class="cm">,</span> <span class="i">SvPV_nolen</span><span class="s">(</span><span class="w">ERRSV</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">"call_Subtract: wanted 1 value from 'Subtract', got %d\n"</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">"%d - %d = %d\n"</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>
<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>
<dl>
<dt>1.</dt><dd>
<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>
</dd>
<dt>2.</dt><dd>
<p>The code</p>
<pre class="verbatim"><ol><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">ERRSV</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">"Uh oh - %s\n"</span><span class="cm">,</span> <span class="i">SvPV_nolen</span><span class="s">(</span><span class="w">ERRSV</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>
<pre class="verbatim"><ol><li> <a class="l_k" href="functions/print.html">print</a> <span class="q">"Uh oh - $@\n"</span> <a class="l_k" href="functions/if.html">if</a> <span class="i">$@</span><span class="sc">;</span></li></ol></pre><p><code class="inline"><span class="w">PL_errgv</span></code>
is a perl global of type <code class="inline"><span class="w">GV</span> *</code>
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>
.</p>
</dd>
<dt>3.</dt><dd>
<p>Note that the stack is popped using <code class="inline"><span class="w">POPs</span></code>
in the block where
<code class="inline"><span class="i">SvTRUE</span><span class="s">(</span><span class="w">ERRSV</span><span class="s">)</span></code>
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
the stack be tidied up by removing the <i>undef</i>.</p>
</dd>
</dl>
<a id="Using-G_KEEPERR"></a><h3 class='h3' >Using G_KEEPERR</h3>
<p>Consider this rather facetious example, where we have used an XS
version of the call_Subtract example above inside a destructor:</p>
<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">"death can be fatal"</span> <a class="l_k" href="functions/if.html">if</a> <span class="i">$a</span> < <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">"foo dies"</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">->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">->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">"Saw: $@"</span> <a class="l_k" href="functions/if.html">if</a> <span class="i">$@</span><span class="sc">;</span> <span class="c"># should be, but isn't</span></li></ol></pre><p>This example will fail to recognize that an error occurred inside the
<code class="inline"><a class="l_k" href="functions/eval.html">eval</a> <span class="s">{</span><span class="s">}</span></code>
. Here's why: the call_Subtract code got executed while perl
was cleaning up temporaries when exiting the outer braced block, and because
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>
<pre class="verbatim"><ol><li> <span class="w">count</span> = <span class="i">call_pv</span><span class="s">(</span><span class="q">"Subtract"</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>
<a id="Using-call_sv"></a><h3 class='h3' >Using call_sv</h3>
<p>In all the previous examples I have 'hard-wired' the name of the Perl
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
within the Perl script.</p>
<p>Consider the Perl code below</p>
<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">"Hello there\n"</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">"fred"</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> <span class="w">void</span></li><li> <span class="i">CallSubPV</span><span class="s">(</span><span class="w">name</span><span class="s">)</span></li><li> <span class="w">char</span> * <span class="w">name</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">call_pv</span><span class="s">(</span><span class="w">name</span><span class="cm">,</span> <span class="w">G_DISCARD</span>|<span class="w">G_NOARGS</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>That is fine as far as it goes. The thing is, the Perl subroutine
can be specified as only a string, however, Perl allows references
to subroutines and anonymous subroutines.
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
that the <code class="inline"><span class="w">name</span></code>
parameter is now defined as an SV* and we use
<i>call_sv</i> instead of <i>call_pv</i>.</p>
<pre class="verbatim"><ol><li> <span class="w">void</span></li><li> <span class="i">CallSubSV</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="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">call_sv</span><span class="s">(</span><span class="w">name</span><span class="cm">,</span> <span class="w">G_DISCARD</span>|<span class="w">G_NOARGS</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>Because we are using an SV to call <i>fred</i> the following can all be used:</p>
<pre class="verbatim"><ol><li> <span class="i">CallSubSV</span><span class="s">(</span><span class="q">"fred"</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">CallSubSV</span><span class="s">(</span>\<span class="i">&fred</span><span class="s">)</span><span class="sc">;</span></li><li> <span class="i">$ref</span> = \<span class="i">&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">"Hello there\n"</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
how you can specify the Perl subroutine.</p>
<p>You should note that, if it is necessary to store the SV (<code class="inline"><span class="w">name</span></code>
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
pointer to the SV. Say the code above had been like this:</p>
<pre class="verbatim"><ol><li> <span class="w">static</span> <span class="w">SV</span> * <span class="w">rememberSub</span><span class="sc">;</span></li><li></li><li> <span class="w">void</span></li><li> <span class="i">SaveSub1</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="w">rememberSub</span> = <span class="w">name</span><span class="sc">;</span></li><li></li><li> <span class="w">void</span></li><li> <span class="i">CallSavedSub1</span><span class="s">(</span><span class="s">)</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">call_sv</span><span class="s">(</span><span class="w">rememberSub</span><span class="cm">,</span> <span class="w">G_DISCARD</span>|<span class="w">G_NOARGS</span><span class="s">)</span><span class="sc">;</span></li></ol></pre><p>The reason this is wrong is that, by the time you come to use the
pointer <code class="inline"><span class="w">rememberSub</span></code>
in <code class="inline"><span class="w">CallSavedSub1</span></code>
, it may or may not still refer
to the Perl subroutine that was recorded in <code class="inline"><span class="w">SaveSub1</span></code>
. This is
particularly true for these cases:</p>
<pre class="verbatim"><ol><li> <span class="i">SaveSub1</span><span class="s">(</span>\<span class="i">&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">"Hello there\n"</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>
statements above has been executed,
the SV*s which corresponded to the parameters will no longer exist.
Expect an error message from Perl of the form</p>
<pre class="verbatim"><ol><li> <span class="w">Can'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>
lines.</p>
<p>Similarly, with this code</p>
<pre class="verbatim"><ol><li> <span class="i">$ref</span> = \<span class="i">&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
the version of Perl you are using)</p>
<pre class="verbatim"><ol><li> <span class="w">Not</span> <span class="w">a</span> <span class="w">CODE</span> <span class="w">reference</span> <span class="w">at</span> ...</li><li> <span class="w">Undefined</span> <span class="w">subroutine</span> <span class="i">&main::47</span> <span class="w">called</span> ...</li></ol></pre><p>The variable $ref may have referred to the subroutine <code class="inline"><span class="w">fred</span></code>
whenever the call to <code class="inline"><span class="w">SaveSub1</span></code>
was made but by the time
<code class="inline"><span class="w">CallSavedSub1</span></code>
gets called it now holds the number <code class="inline"><span class="n">47</span></code>
. Because we
saved only a pointer to the original SV in <code class="inline"><span class="w">SaveSub1</span></code>
, any changes to
$ref will be tracked by the pointer <code class="inline"><span class="w">rememberSub</span></code>
. This means that
whenever <code class="inline"><span class="w">CallSavedSub1</span></code>
gets called, it will attempt to execute the
code which is referenced by the SV* <code class="inline"><span class="w">rememberSub</span></code>
. 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>
<p>A similar but more subtle problem is illustrated with this code:</p>
<pre class="verbatim"><ol><li> <span class="i">$ref</span> = \<span class="i">&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">&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>
gets called it will execute the Perl
subroutine <code class="inline"><span class="w">joe</span></code>
(assuming it exists) rather than <code class="inline"><span class="w">fred</span></code>
as was
originally requested in the call to <code class="inline"><span class="w">SaveSub1</span></code>
.</p>
<p>To get around these problems it is necessary to take a full copy of the
SV. The code below shows <code class="inline"><span class="w">SaveSub2</span></code>
modified to do that.</p>
<pre class="verbatim"><ol><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>
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
subroutine <code class="inline"><span class="w">name</span></code>
is copied to the variable <code class="inline"><span class="w">keepSub</span></code>
in one
operation using <code class="inline"><span class="w">newSVsv</span></code>
. Thereafter, whenever <code class="inline"><span class="w">SaveSub2</span></code>
is called,
the existing SV, <code class="inline"><span class="w">keepSub</span></code>