/
perlcall.pod
3940 lines (2662 loc) · 116 KB
/
perlcall.pod
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
=encoding utf8
=head1 NAME
=begin original
perlcall - Perl calling conventions from C
=end original
perlcall - C からの Perl 呼び出し規約
=head1 DESCRIPTION
=begin original
The purpose of this document is to show you how to call Perl subroutines
directly from C, i.e., how to write I<callbacks>.
=end original
このドキュメントの目的は、どのようにして Perl のサブルーチンを C から
直接呼び出すか、つまり I<コールバック> の書き方を示すことです。
=begin original
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.
=end original
コールバックを記述するための Perl から提供される C の
インターフェースについての議論とは別に、本ドキュメントでは実践的な
インターフェースを例で示します。
それに加え、コールバックをコーディングするための幾つかの
テクニックがカバーされます。
=begin original
Examples where callbacks are necessary include
=end original
必要に応じて、例を示すようにしてあります。
=over 5
=item * An Error Handler
(エラーハンドラ)
=begin original
You have created an XSUB interface to an application's C API.
=end original
あるアプリケーションの C API へのインタフェース XSUB を作成しました。
=begin original
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.
=end original
アプリケーションでかなり一般的な機能として、なにか面倒が起こったときに
呼ぶことのできる C の関数を定義することができるようにすることが
挙げられます。
やりたいことは、代わりに Perl サブルーチンを呼ぶということです。
=item * An Event-Driven Program
(イベント駆動プログラム)
=begin original
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.
=end original
どこでコールバックが使われるかの古典的な例は、X11 アプリケーションのような
イベントドリブンなプログラムに見られます。
この場合登録内容は、マウスのボタンが押されたりカーソルが
ウィンドウやメニューアイテムを選択したといった特定のイベントが
発生したときに呼びだされるように機能します。
=back
=begin original
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
L<perlembed>.
=end original
記述したテクニックは、Perl プログラムを C のプログラムに埋め込むときにも
適用できますが、それはこのドキュメントの本来の目的ではありません。
Perl を組み込むことに特化したその他の詳細や考慮しなければならないことが
あります。
C に Perl を埋め込むことの詳細は L<perlembed> を参照してください。
=begin original
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--L<perlxs>
and L<perlguts>.
=end original
このドキュメントの先に進む前に、L<perlxs> と L<perlguts> という
二つのドキュメントを読んでおいたほうが良いでしょう。
=head1 THE CALL_ FUNCTIONS
(CALL_ 関数)
=begin original
Although this stuff is easier to explain using examples, you first need
be aware of a few important definitions.
=end original
これらの性質は例を使って説明するのが簡単であるにも関らず、あなたは
まず幾つかの重要な定義を知ることが必要です。
=begin original
Perl has a number of C functions that allow you to call Perl
subroutines. They are
=end original
Perl には、Perl のサブルーチンを呼ぶことを許している C の関数が
たくさんあります。
それを以下に示します。
I32 call_sv(SV* sv, I32 flags);
I32 call_pv(char *subname, I32 flags);
I32 call_method(char *methname, I32 flags);
I32 call_argv(char *subname, I32 flags, char **argv);
=begin original
The key function is I<call_sv>. 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>
to invoke the Perl subroutine.
=end original
中心となる関数は I<call_sv> です。
他の全ての関数は特別な状況で
Perl サブルーチンを呼び出しやすくするための単純なラッパーです。
最終的にはこれらの関数はすべて I<call_sv> を呼び出して
Perl サブルーチンを起動します。
=begin original
All the I<call_*> functions have a C<flags> 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 L</FLAG VALUES>.
=end original
関数 I<call_*> は Perl に対するオプションのビットマスクを
渡すのに使われる C<flags> 引数を取ります。
このビットマスクはそれぞれの関数で全く同じように働きます。
設定可能なビットマスクは L</FLAG VALUES> で述べられています。
=begin original
Each of the functions will now be discussed in turn.
=end original
関数のそれぞれに対する説明を始めましょう。
=over 5
=item call_sv
=begin original
I<call_sv> takes two parameters. The first, C<sv>, 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, L</Using call_sv>, shows how you can make
use of I<call_sv>.
=end original
I<call_sv> は二つのパラメータをとります。
第一引数が SV* である C<sv> です。
これにより、呼び出す Perl サブルーチンを C の文字列(この場合
最初に SV に変換されます)としても、サブルーチンに対する
リファレンスとしても指定することができます。
セクション L</Using call_sv> で、
どのように I<call_sv> を使えるかを示します。
=item call_pv
=begin original
The function, I<call_pv>, is similar to I<call_sv> except it
expects its first parameter to be a C char* which identifies the Perl
subroutine you want to call, e.g., C<call_pv("fred", 0)>. If the
subroutine you want to call is in another package, just include the
package name in the string, e.g., C<"pkg::fred">.
=end original
関数 I<call_pv> は I<call_sv> と似ていますが、
C<call_pv("fred", 0)> のように呼び出したい Perl サブルーチンを
指定する第一引数に C の char * が来ることを期待しているという点が
異なります。
呼び出したいサブルーチンが別のパッケージに置かれている場合、
文字列にパッケージ名を含め C<"pkg::fred"> のようにします。
=item call_method
=begin original
The function I<call_method> is used to call a method from a Perl
class. The parameter C<methname> 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 L<perlobj> for more information on
static and virtual methods and L</Using call_method> for an example
of using I<call_method>.
=end original
関数 I<call_method> は Perl のクラスからメソッドを呼び出すのに使われます。
C<methname> というパラメータは呼び出すメソッドの名前に対応します。
メソッドの所属するクラスは、パラメータリストではなく
Perlのスタックで渡されるということに注意してください。
このクラスは、クラスの名前(静的メソッドに対する場合)であっても
オブジェクトに対するリファレンスであってもかまいません。
静的メソッドと仮想メソッドに関する詳細は L<perlobj> を、I<call_method> を
使った例は L</Using call_method> を参照してください。
=item call_argv
=begin original
I<call_argv> calls the Perl subroutine specified by the C string
stored in the C<subname> parameter. It also takes the usual C<flags>
parameter. The final parameter, C<argv>, consists of a NULL-terminated
list of C strings to be passed as parameters to the Perl subroutine.
See L</Using call_argv>.
=end original
I<call_argv> はパラメータ C<subname> に格納された C 文字列で
指定された Perl サブルーチンを呼び出します。
これはまた、C<flags> パラメータを取ります。
最後のパラメータ C<argv> は、Perl サブルーチンに渡されるパラメータである
C 文字列の、NULL で終端されたリストから構成されます。
L</Using call_argv> を参照してください。
=back
=begin original
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.
=end original
上記の関数はすべて整数値を返します。
これは、Perl サブルーチンが返したアイテムの数です。
サブルーチンから返された実際のアイテムは Perl スタックに
格納されています。
=begin original
As a general rule you should I<always> 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.
=end original
一般的な規則として、あなたは B<いつでも> これらの関数の戻り値を
チェックすべきです。
あなたが Perl サブルーチンから返される値として、
ある特定の数だけを期待していたとしても、誰かが予期しないなにかを
行うことを止める手だてはないので -- 自分は警告されていない、とは
云わないでください。
=head1 FLAG VALUES
(フラグの値)
=begin original
The C<flags> parameter in all the I<call_*> functions is one of C<G_VOID>,
C<G_SCALAR>, or C<G_ARRAY>, which indicate the call context, OR'ed together
with a bit mask of any combination of the other G_* symbols defined below.
=end original
すべての C<call_*> 関数のパラメータ C<flags> は、呼び出しコンテキストを示す
C<G_VOID>, C<G_SCALAR>, C<G_ARRAY> の一つに、以下に定義するその他の
G_* シンボルの組み合わせのビットマスクを「論理和」で組み合わせて用います。
=head2 G_VOID
=for apidoc AmnUh||G_VOID
=begin original
Calls the Perl subroutine in a void context.
=end original
Perl のサブルーチンを無効コンテキストで呼び出します。
=begin original
This flag has 2 effects:
=end original
このフラグには二つの効果があります。
=over 5
=item 1.
=begin original
It indicates to the subroutine being called that it is executing in
a void context (if it executes I<wantarray> the result will be the
undefined value).
=end original
サブルーチンの呼び出しが無効コンテキスト(もし I<wantarray> を実行すると
その結果は未定義値となります)において実行されることを示します。
=item 2.
=begin original
It ensures that nothing is actually returned from the subroutine.
=end original
サブルーチンから実際に返されるものがなにもないことを保証します。
=back
=begin original
The value returned by the I<call_*> function indicates how many
items have been returned by the Perl subroutine--in this case it will
be 0.
=end original
関数 I<call_*> の戻り値は Perl のサブルーチンがアイテムを幾つ
返したのかを示します--この例の場合は、0 となります。
=head2 G_SCALAR
=for apidoc AmnUh||G_SCALAR
=begin original
Calls the Perl subroutine in a scalar context. This is the default
context flag setting for all the I<call_*> functions.
=end original
Perl のサブルーチンをスカラコンテキストで呼び出します。
これはすべての I<call_*> 関数に対するデフォルトのコンテキストの設定です。
=begin original
This flag has 2 effects:
=end original
このフラグには二つの効果があります。
=over 5
=item 1.
=begin original
It indicates to the subroutine being called that it is executing in a
scalar context (if it executes I<wantarray> the result will be false).
=end original
サブルーチンに対して、スカラコンテキストで実行されるということを
示します(I<wantarray> を実行した場合、結果は偽となります)。
=item 2.
=begin original
It ensures that only a scalar is actually returned from the subroutine.
The subroutine can, of course, ignore the I<wantarray> and return a
list anyway. If so, then only the last element of the list will be
returned.
=end original
サブルーチンから実際に返されるものはスカラだけであるということを
保証します。
もちろん、サブルーチンは I<wantarray> を無視し、リストを
返すこともできます。
そうした場合、そうしたリストの最後の要素だけが返されることになります。
=back
=begin original
The value returned by the I<call_*> function indicates how many
items have been returned by the Perl subroutine - in this case it will
be either 0 or 1.
=end original
関数 I<call_*> により返された値は、Perl サブルーチンが幾つの
アイテムを返したかということを示します - この場合、0 か 1 かの
いずれかになります。
=begin original
If 0, then you have specified the G_DISCARD flag.
=end original
0 の場合、G_DISCARD フラグが指定されたということです。
=begin original
If 1, then the item actually returned by the Perl subroutine will be
stored on the Perl stack - the section L</Returning a Scalar> 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_*> function. The section L</Returning a List in Scalar
Context> shows an example of this behavior.
=end original
1 の場合、Perl サブルーチンが実際に返したアイテムは Perl スタックに
積まれます - スタックにあるこの値にどのようにアクセスするかはセクション
L</Returning a Scalar> にあります。
Perl サブルーチンが幾つのアイテムを返したかに関係なく、最後の一つだけが
スタック上でアクセス可能であるということを忘れないでください - つまり、
ただ一つの要素からなるリストのように、値が一つだけ置かれるのです。
他のすべてのアイテムは、I<call_*> 関数から制御が戻ったときには
存在しません。
この振る舞いについての例はセクション
L</Returning a List in Scalar Context> にあります。
=head2 G_ARRAY
=for apidoc AmnUh||G_ARRAY
=begin original
Calls the Perl subroutine in a list context.
=end original
Perl サブルーチンをリストコンテキストで呼び出します。
=begin original
As with G_SCALAR, this flag has 2 effects:
=end original
G_SCALAR を指定したときと同様、このフラグにも二つの効果があります。
=over 5
=item 1.
=begin original
It indicates to the subroutine being called that it is executing in a
list context (if it executes I<wantarray> the result will be true).
=end original
サブルーチンが、リストコンテキストで実行されることを示します
(I<wantarray> を実行すると、その結果は真となります)。
=item 2.
=begin original
It ensures that all items returned from the subroutine will be
accessible when control returns from the I<call_*> function.
=end original
関数 I<call_*> から制御が戻ったときに、サブルーチンから返された
すべてのアイテムがアクセス可能であることを保証します。
=back
=begin original
The value returned by the I<call_*> function indicates how many
items have been returned by the Perl subroutine.
=end original
関数 I<call_*> から返される値は、Perl サブルーチンがアイテムを
幾つ返したかを示すものです。
=begin original
If 0, then you have specified the G_DISCARD flag.
=end original
0 の場合、G_DISCARD フラグが指定されたということです。
=begin original
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 L</Returning a List of Values> gives an example of using the
G_ARRAY flag and the mechanics of accessing the returned items from the
Perl stack.
=end original
0 以外の場合、サブルーチンが返したアイテムの個数となります。
これらのアイテムは Perl スタックに置かれます。
セクション L</Returning a List of Values> には G_ARRAY フラグを使った例と、
Perl スタックに置かれたアイテムをアクセスする仕組みの例があります。
=head2 G_DISCARD
=for apidoc AmnUh||G_DISCARD
=begin original
By default, the I<call_*> 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.
=end original
デフォルトでは、関数 I<call_*> は Perl サブルーチンの返したアイテムを
スタックに置きます。
こういったアイテムに用がない場合、このフラグを設定することによって
Perl が自動的にこれらのアイテムを取り除くようにすることを指定できます。
このフラグを使った場合でも、
Perl サブルーチンに対して G_SCALAR か G_ARRAY のいずれかをさらに
指定することで、(Perl サブルーチンが実行される)コンテキストを
指示できるということに注意してください。
=begin original
If you do not set this flag then it is I<very> 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 L</Returning a Scalar> gives details of how to
dispose of these temporaries explicitly and the section L</Using Perl to
Dispose of Temporaries> discusses the specific circumstances where you
can ignore the problem and let Perl deal with it for you.
=end original
このフラグを設定しなかった場合、なんらかの一時変数(たとえば、Perl
サブルーチンに渡されたパラメータであるとかサブルーチンからの戻り値)を
自分自身で破棄することを確実に行うことがB<非常に>重要です。
L</Returning a Scalar> というセクションでは、これら一時変数をどのようにして
陽に破棄するかを説明しており、
L</Using Perl to Dispose of Temporaries> というセクションではこの
問題を無視できる特定の場所や、Perlに後始末をさせることについて
述べています。
=head2 G_NOARGS
=for apidoc AmnUh||G_NOARGS
=begin original
Whenever a Perl subroutine is called using one of the I<call_*>
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 C<@_> array for the Perl subroutine.
=end original
I<call_*> の一つを使って Perl サブルーチンを呼び出したときはいつでも、
サブルーチンに対してパラメータが渡されたということが
デフォルトで仮定されます。
Perl サブルーチンに対してなんのパラメータも渡さないという場合、この
フラグをセットすることで時間を少々節約することができます。
これは Perl サブルーチンに対して、C<@_> を生成しないという
効果を持っています。
=begin original
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.
=end original
このフラグにより提供される機能が直接的なもののように見えるにも関らず、
これを使うのはそうすべき適当な理由があるときのみにすべきでしょう。
このように用心する理由は、G_NOARGS フラグを指定した場合であっても、
呼び出された Perl サブルーチンがパラメータを渡されたと
思い込んでいる可能性があるからです。
=begin original
In fact, what can happen is that the Perl subroutine you have called
can access the C<@_> array from a previous Perl subroutine. This will
occur when the code that is executing the I<call_*> function has
itself been called from another Perl subroutine. The code below
illustrates this
=end original
事実、起こりうる可能性として、呼び出した Perl サブルーチンが以前の
Perl サブルーチンの配列 C<@_> にアクセスできてしまうというものがあります。
これは、I<call_*> 関数を実行するコード自身が、他の Perl サブルーチンから
呼ばれたときに起こり得ます。
以下のコードはこれを説明するものです。
sub fred
{ print "@_\n" }
sub joe
{ &fred }
&joe(1,2,3);
=begin original
This will print
=end original
この結果は次のようになります。
1 2 3
=begin original
What has happened is that C<fred> accesses the C<@_> array which
belongs to C<joe>.
=end original
ここで起こったことは、C<fred> が C<joe> に属する配列 C<@_> に
アクセスしているということです。
=head2 G_EVAL
=for apidoc AmnUh||G_EVAL
=begin original
It is possible for the Perl subroutine you are calling to terminate
abnormally, e.g., by calling I<die> 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 { }>
around the subroutine call.
=end original
呼び出す Perl サブルーチンを、I<die> を陽に呼び出したり、何かが
存在しなかったことにより即座に終了させることを可能にします。
デフォルトでは、そういったイベントが起こった場合にはプロセスは即座に
終了します。
しかしこの種のイベントをトラップしたいのなら、G_EVAL フラグを指定します。
それによって、サブルーチンの呼び出しを I<eval { }> で囲むようになります。
=begin original
Whenever control returns from the I<call_*> function you need to
check the C<$@> variable as you would in a normal Perl script.
=end original
I<call_*> 関数から戻ってきたときは、いつでも通常の Perl スクリプトで
そうするように変数 C<$@> をチェックする必要があります。
=begin original
The value returned from the I<call_*> 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:
=end original
I<call_*> から返された値は、他に指定したフラグとエラーが
起きたかどうかに依存します。
以下に起こりうるすべてのケースを挙げます。
=over 5
=item *
=begin original
If the I<call_*> function returns normally, then the value
returned is as specified in the previous sections.
=end original
関数 I<call_*> から正常に戻ってきた場合、戻り値は前のセクションで
説明したようなものです。
=item *
=begin original
If G_DISCARD is specified, the return value will always be 0.
=end original
G_DISCARD が指定されていた場合、戻り値は常に 0 になります。
=item *
=begin original
If G_ARRAY is specified I<and> an error has occurred, the return value
will always be 0.
=end original
G_ARRAY が指定されていて、B<かつ>、エラーが発生した場合には戻り値は
常に 0 となります。
=item *
=begin original
If G_SCALAR is specified I<and> an error has occurred, the return value
will be 1 and the value on the top of the stack will be I<undef>. This
means that if you have already detected the error by checking C<$@> and
you want the program to continue, you must remember to pop the I<undef>
from the stack.
=end original
G_SCALAR が指定されていて、B<かつ>、エラーが発生した場合には戻り値は
1となり、そしてスタックトップにある値は I<undef> となります。
これは C<$@> を検査することで既にエラーを検出していていてプログラムの
継続を望んでいる場合には、スタックから I<undef> を忘れずに
ポップしなければならないということです。
=back
=begin original
See L</Using G_EVAL> for details on using G_EVAL.
=end original
G_EVAL の使用についての詳細は L</Using G_EVAL> を参照してください。
=head2 G_KEEPERR
=for apidoc AmnUh||G_KEEPERR
=begin original
Using the G_EVAL flag described above will always set C<$@>: 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.
=end original
上述の G_EVAL フラグを使うと、常に C<$@> を設定します: エラーがなければ
クリアし、呼び出したコードにエラーがあればエラーを記述します。
これは、可能性のあるエラーを扱おうとするのが目的なら求めているものですが、
単にエラーをトラップしてプログラムの残りを侵害するのを止めたいだけかも
しれません。
=begin original
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 C<__DIE__> or C<__WARN__>
hooks, and C<tie> functions.
=end original
このシナリオは、デストラクタの中から呼ばれるようなコード、非同期な
コールバック、シグナルハンドラといったもので最も有用です。
このような状況では、呼び出されたコードは周りの動的な内容とは
ほとんど関係がなく、メインプログラムは、例え理性的に扱えなくても、
呼び出されたコードのエラーから隔離される必要があります。
また、こうするのは C<__DIE__> や C<__WARN__> フックのコードや、
C<tie> 関数で有用かもしれません。
=begin original
The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
I<call_*> functions that are used to implement such code, or with
C<eval_sv>. This flag has no effect on the C<call_*> functions when
G_EVAL is not used.
=end original
G_KEEPERR フラグは、実装したコードを使用する I<call_*> において
G_EVAL と、または C<eval_sv> と組み合わせて使われます。
このフラグは G_EVAL が使われていないときにはなんの効果も持ちません。
=begin original
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 C<$@>. Instead the error will be
converted into a warning, prefixed with the string "\t(in cleanup)".
This can be disabled using C<no warnings 'misc'>. If there is no error,
C<$@> will not be cleared.
=end original
G_KEEPERR が使われると、呼び出されたコードのエラーは通常通り
呼び出しを終了させ、(G_EVAL での通常通り)エラーは呼び出しを超えて
伝搬しませんが、C<$@> は設定されません。
エラーが警告に変換される代わりに、"\t(in cleanup)" という文字列が
前置されます。
これは C<no warnings 'misc'> を使って無効にできます。
エラーがなければ、C<$@> はクリアされません。
=begin original
Note that the G_KEEPERR flag does not propagate into inner evals; these
may still set C<$@>.
=end original
G_KEEPERR フラグは内側の eval に伝搬しないことに注意してください;
これらは未だに C<$@> を設定します。
=begin original
The G_KEEPERR flag was introduced in Perl version 5.002.
=end original
G_KEEPERR フラグは Perl のバージョン 5.002 で導入されました。
=begin original
See L</Using G_KEEPERR> for an example of a situation that warrants the
use of this flag.
=end original
このフラグを使うことが正当である状況の例が L</Using G_KEEPERR> にあります。
=head2 Determining the Context
(コンテキストを決定する)
=begin original
As mentioned above, you can determine the context of the currently
executing subroutine in Perl with I<wantarray>. The equivalent test
can be made in C by using the C<GIMME_V> macro, which returns
C<G_ARRAY> if you have been called in a list context, C<G_SCALAR> if
in a scalar context, or C<G_VOID> if in a void context (i.e., the
return value will not be used). An older version of this macro is
called C<GIMME>; in a void context it returns C<G_SCALAR> instead of
C<G_VOID>. An example of using the C<GIMME_V> macro is shown in
section L</Using GIMME_V>.
=end original
先に説明したように、I<wantarray> を使ってサブルーチンが実行されている
コンテキストを判定することができます。
これと同じことが、C<GIMME_V> マクロを使うことでも可能です; このマクロは
リストコンテキストで呼ばれた場合には C<G_ARRAY> を、スカラコンテキストで
呼ばれた場合には C<G_SCALAR> を、無効コンテキストの場合(たとえば戻り値が
使われないとき)には C<G_VOID> を返します。
このマクロの古いバージョンは C<GIMME> という名前で、無効コンテキストのときに
C<G_VOID> の代わりに C<G_SCALAR> を返していました。
C<GIMME_V> マクロの使用例はセクション L</Using GIMME_V> にあります。
=head1 EXAMPLES
(例)
=begin original
Enough of the definition talk! Let's have a few examples.
=end original
定義の話は十分でしょう!
いくつか例を示します。
=begin original
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.
=end original
Perl では、Perl スタックをアクセスする手助けのためのマクロをたくさん
用意しています。
Perl の内部ルーチンとのインターフェースには、
常にこれらのマクロを使うようにすべきでしょう。
将来 Perl に施される変更に対しても、これを使うことで、コードの方への
影響が少なくなるはずです。
=begin original
Another point worth noting is that in the first series of examples I
have made use of only the I<call_pv> 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> and
I<call_sv>, you should always try to use I<call_sv>. See
L</Using call_sv> for details.
=end original
もう一つ余計なことを言っておくと、最初のいくつかの例では、
I<call_pv> 関数だけを使っています。
これは、単にみなさんがこの話題に入り込みやすいようにと
考えただけのことです。
I<call_pv> と I<call_sv> のどちらも使える場合、常に I<call_sv> を
使うことを試してください。
詳しくは L</Using call_sv> を参照してください。
=head2 No Parameters, Nothing Returned
(引数なし、戻り値なしの場合)
=begin original
This first trivial example will call a Perl subroutine, I<PrintUID>, to
print out the UID of the process.
=end original
最初の明快な例は、プロセスの UID を出力するために Perl サブルーチン
I<PrintUID> を呼びだします。
sub PrintUID
{
print "UID is $<\n";
}
=begin original
and here is a C function to call it
=end original
そして、これを呼び出す C 関数です
static void