perlXStut - XSUB を書くためのチュートリアル
このチュートリアルは読者にPerlのエクステンションを作るのに必要な ステップを教えるものです。 読者が perlguts, perlapi, perlxs にアクセスできるということを 仮定しています。
このチュートリアルは非常に単純な例から始めて、新しい例に進むごとに 新たな機能を付加えたより複雑なものへとなります。 幾つかのコンセプトは、読者がエクステンションを作成するのが徐々に 簡単になるように、チュートリアルの後のほうまで完全には説明されません。
このチュートリアルは Unix の観点から書かれています。 (Win32 のように)ほかのプラットフォームでは異なることになると知っている 場所では、それを記しています。 何か見落としを発見したら、ぜひ教えてください。
このチュートリアルでは、Perl が使用するように設定されている
make プログラムが make という名前であると想定しています。
以下の例で "make" を実行する代わりに、Perl が使うように設定された他の
make プログラムを代用する必要があるかもしれません。
perl -V:make とすると、それが何かがわかります。
一般向けに Perl エクステンションを書くとき、あなたのマシンで 利用可能なバージョンと異なるバージョンの Perl でエクステンションが 使われることを想定するべきです。 この文書を読んでいるということは、あなたのマシンの Perl のバージョンは おそらく 5.005 以降でしょうが、エクステンションのユーザーはもっと古い バージョンかもしれません。
どのような非互換性が想定されるかを理解するために、また珍しい場合として、 マシンに入っている Perl のバージョンがこのドキュメントより古い場合、 さらなる情報は "Troubleshooting these Examples" の章を参照してください。
もしエクステンションが、Perl の古いリリースでは利用できないような Perl の 機能を使っているなら、ユーザーは早期の意味のある警告で理解します。 おそらくこの情報を README ファイルに追加するべきでしょうが、最近の エクステンションのインストールは、CPAN.pm モジュールやその他の ツールによって自動的に行われるかもしれません。
MakeMaker ベースのインストールでは、Makefile.PL が、プラットフォームの バージョンチェックの最も早い機会を提供します。 この目的のために、以下のようなものを Makefile.PL に書けます:
eval { require 5.007 }
or die <<EOD;
############
### This module uses frobnication framework which is not available before
### version 5.007 of Perl. Upgrade your Perl before installing Kara::Mba.
############
EOD
一般的には、システムがライブラリを動的にロードする機能を持っていなければ XSUB を作成することはできないと考えられています。 これは正しくありません。 あなたは XSUB を作ることが できます。 ただし、あなたはその XSUB のサブルーチンと、Perl とをリンクして新たな 実行ファイルを作らなければなりません。 この状況は perl4 と同じです。
このチュートリアルはまだそういったシステムを使っていても大丈夫です。 XSUB の作成機能は、システムをチェックして可能であれば動的ロード可能 ライブラリを作成し、できなければスタティックライブラリを作成してから そのスタティックライブラリをリンクしてスタティックリンクされた 実行ファイルを作成します(最後の部分はオプション)。
これからの例を使って、動的ロード可能ライブラリが使えるシステムで
あってもスタティックリンクされた実行ファイルを作成したいという場合、
"make"という引数なしのコマンドを実行する代わりに、
"make perl" というコマンドを実行してください。
もしスタティックリンクされた実行ファイルを作成することを選んだのなら、
"make test" の代わりに "make test_static" を使ってください。
動的ロード可能ライブラリが作成できないシステムの場合には単に
"make test" とするだけで OK です。
では、見ていきましょう!
最初のエクステンションは非常に単純です。 エクステンションの中でルーチンを呼び出すときに、良く知られたメッセージを 出力してリターンします。
"h2xs -A -n Mytest" を実行します。
これは Mytest という名前のディレクトリを作成しますが、カレントの
作業ディレクトリに ext/ というディレクトリがあればその下に作成します。
MANIFEST, Makefile.PL, lib/Mytest.pm, Mytest.xs, t/Mytest.t, Changes を
含めた幾つかのファイルがディレクトリ Mytest の下に作成されます。
MANIFEST というファイルには Mytest ディレクトリに生成されたファイル すべてのファイル名があります。
Makefile.PL というファイルは以下のような形式であるべきです。
use ExtUtils::MakeMaker;
# See lib/ExtUtils/MakeMaker.pm for details of how to influence
# the contents of the Makefile that is written.
WriteMakefile(
NAME => 'Mytest',
VERSION_FROM => 'Mytest.pm', # finds $VERSION
LIBS => [''], # e.g., '-lm'
DEFINE => '', # e.g., '-DHAVE_SOMETHING'
INC => '', # e.g., '-I/usr/include/other'
);
Mytest.pm は以下のような内容で始まります。
package Mytest;
use 5.008008;
use strict;
use warnings;
require Exporter;
our @ISA = qw(Exporter);
our %EXPORT_TAGS = ( 'all' => [ qw(
) ] );
our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
our @EXPORT = qw(
);
our $VERSION = '0.01';
require XSLoader;
XSLoader::load('Mytest', $VERSION);
# Preloaded methods go here.
1;
__END__
# Below is the stub of documentation for your module. You better edit it!
.pm ファイルの残りはエクステンションのためのドキュメントをを提供するための サンプルコードからなります。
最後に、Mytest.xs の内容は以下のようになります。
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
#include "ppport.h"
MODULE = Mytest PACKAGE = Mytest
.xs ファイルの終わりに以下の行を追加します。
void
hello()
CODE:
printf("Hello, world!\n");
"CODE:" で始まる行がインデントされていないのは問題ありません。 しかし、読みやすさの観点から、CODE: を 1 レベルインデントして、 引き続く行をさらに 1 レベルインデントすることを勧めます。
ここで、"perl Makefile.PL" を実行します。
これで make が必要とする本当の Makefile が生成されます。
この出力は以下のようになります:
% perl Makefile.PL
Checking if your kit is complete...
Looks good
Writing Makefile for Mytest
%
ここでmakeを実行すれば、以下のような出力が生成されます (一部の長い行は明快さを保つために短くし、一部の余分な行は削除しています):
% make
cp lib/Mytest.pm blib/lib/Mytest.pm
perl xsubpp -typemap typemap Mytest.xs > Mytest.xsc && mv Mytest.xsc Mytest.c
Please specify prototyping behavior for Mytest.xs (see perlxs manual)
cc -c Mytest.c
Running Mkbootstrap for Mytest ()
chmod 644 Mytest.bs
rm -f blib/arch/auto/Mytest/Mytest.so
cc -shared -L/usr/local/lib Mytest.o -o blib/arch/auto/Mytest/Mytest.so \
\
chmod 755 blib/arch/auto/Mytest/Mytest.so
cp Mytest.bs blib/arch/auto/Mytest/Mytest.bs
chmod 644 blib/arch/auto/Mytest/Mytest.bs
Manifying blib/man3/Mytest.3pm
%
"prototyping behavior" に関する行は安全に無視できます - これは The PROTOTYPES: Keyword in perlxs で説明されています。
Win32 システムの場合で、C ライブラリ中の関数に関するリンカのエラーで ビルド処理が失敗する場合、Perl が PerlCRT を使うように設定されているかを 調べて見てください (この場合、perl -V:libc を実行すればわかるはずです)。 もし Perl が PerlCRT を使うように設定されているなら、PerlCRT.lib を msvcrt.lib と同じ位置にコピーして、コンパイラがこれを見つけられるように する必要があります。 msvcrt.lib は普通 Visual C コンパイラの lib ディレクトリ (例えば C:/DevStudio/VC/lib) にあります。
Perl にはテストスクリプトを簡単に書くための独自の特別な方法がありますが、 この例のためだけに、自分でテストスクリプトを作ります。 hello という名前の、以下のような内容のファイルを作ります。
#! /opt/perl5/bin/perl
use ExtUtils::testlib;
use Mytest;
Mytest::hello();
ここでスクリプトを実行可能にして(chmod +x hello)から実行すれば、
以下のような出力になるはずです。
% ./hello
Hello, world!
%
今度は、数値引数を入力として一つ取り、その数値が偶数なら 1 を、奇数なら 0 を返すようなサブルーチンを追加しましょう。
以下の行を Mytest.xs の末尾に追加します:
int
is_even(input)
int input
CODE:
RETVAL = (input % 2 == 0);
OUTPUT:
RETVAL
"int input" の行の始めにある空白は必須ではありませんが、これがあると
読みやすさが増します。
同様に、行末のセミコロンも省略可能です。
任意の空白を "int" と "input" の間に置くことができます。
make を再度実行して、新たな共有ライブラリを作ります。
前のステップと同じように、Makefile.PL から Makefile を作って make を実行します。
作成したエクステンションが動作するかを確認するために、Mytest.t の ようなファイルが必要となります。 このファイルは Perl 自身が持っている構造をチェックするのと同様のものを 模倣して作ります。 テストスクリプトの中では、エクステンションの動作を確認するたくさんの テストを置き、正しい動作をしたら "ok" を正しくなければ "not ok" を 出力するようにします。 BEGIN ブロックにある文を print "1..4" に変え、ファイルの末尾に以下の行を 追加します。
use Test::More tests => 4;
BEGIN { use_ok('Mytest') };
#########################
# Insert your test code below, the Test::More module is use()ed here so read
# its man page ( perldoc Test::More ) for help writing this test script.
is(&Mytest::is_even(0), 1);
is(&Mytest::is_even(1), 0);
is(&Mytest::is_even(2), 1);
"make test" というコマンドでテストスクリプトを呼び出します。
以下のような出力が出るはずです。
%make test
PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/Mytest....ok
All tests successful.
Files=1, Tests=4, 0 wallclock secs ( 0.03 cusr + 0.00 csys = 0.03 CPU)
%
プログラム h2xs はエクステンションを作成する出発点となります。 後の例では、ヘッダファイルを読み込んで C のルーチンに対する 接点のテンプレートを生成するのに h2xs をどのように使うかを示します。
h2xs はエクステンションのディレクトリに数多くのファイルを作成します。 Makefile.PL というファイルはエクステンションを作成するための 本当の Makefile を生成する perl スクリプトです。 詳細は後述します。
.pm と .xs といったファイルはエクステンションの本体を含みます。 .xs ファイルにはエクステンションを作るための C のルーチンがあります。 .pm ファイルには Perl がどのようにあなたの作ったエクステンションを ロードするかを指示するルーチンがあります。
Makefile を生成し、make を実行することでカレントの作業ディレクトリの
下に blib ( "build library" を意味します)と呼ばれるディレクトリが
作られます。
このディレクトリには、私たちが作成する共有ライブラリが置かれます。
一度それをテストすれば、最終的な場所にインストールすることができます。
"make test" 経由でテストスクリプトを実行することによって、非常に重要な
幾つかのことを行います。
これは perl に -I 引数を付けて起動し、これによりエクステンションの
一部である様々なファイルを見つけることができるようにします。
エクステンションをテストするのに "make test" を使うのは 非常に
重要です。
もし、テストスクリプトをそのまま実行してしまったら、致命的なエラーが
発生するでしょう。
テストスクリプトを実行するのに "make test" を使うもう一つの重大な
理由は、既にあるエクステンションをアップグレードしたものを
テストしようとしたときに、"make test" を使っていれば、既に
あるものではなく、新しいものをテストすることが保証されるためです。
Perl が use extension; という行を見つけたとき、use する
エクステンションと同じ名前で .pm という拡張を持つファイルを検索します。
もしそういったファイルが見つからなければ、Perl は致命的エラーにより
終了します。
デフォルトの検索パスは @INC という配列に置かれます。
Mytest.pm は perl に Exporter エクステンション と Dynamic Loader
エクステンションが必要であるいうことを教えます。
この後配列 @ISA, @EXPORT とスカラー $VERSION に値を設定し、最後に
モジュールをブートストラップするように perl に指示します。
perl はそのダイナミックローダールーチンを(あれば)呼び出し、共有ライブラリを
ロードします。
@ISA と @EXPORT の二つの配列は非常に重要です。
配列 @ISA には、メソッド(もしくはサブルーチン)がカレントパッケージに
なかったときに探しに行く他のパッケージのリストがあります。
これは普通オブジェクト指向エクステンション(これについてはずっと後の方で
議論します)でのみ重要なので、普通は修正する必要はありません。
配列 @EXPORT は Perl に対して、呼び出されたときにパッケージの名前空間に
置くべきエクステンションの変数とサブルーチンを指示します。
ユーザーが既にあなたの変数名やサブルーチン名を使っているかどうかは
わからないので、何をエクスポートするかを慎重に選択することは極めて
重要です。
何かそうするべき理由がない限りは、メソッド名や変数名を
デフォルトでは エクスポート しない ようにしてください。
一般的な規則として、モジュールがオブジェクト指向しようとした場合には 何もエクスポートしません。 モジュールが単なる関数と変数の集まりであれば、別の配列 @EXPORT_OK を 通じてそれらをエクスポートできます。 この配列は、ユーザーがそうしてほしと明示的に指定しない限り、 自動的にはサブルーチン名と変数名を名前空間に置きません。
詳細は perlmod を参照してください。
変数 $VERSION は .pm ファイルと共有ライブラリがそれぞれ
「同期している」ことを保証します。
.pm ファイルや .xs ファイルを変更したとき、この変数の値を
増加させるべきです。
良いテストスクリプトを書くことの重要性は、いくら強調しても足りません。 Perl 自身が使っている "ok/not ok" の形式を忠実に守り、テストケースで どうなったかを簡単に、曖昧なことなくわかるようにします。 バグを発見して修正したら、テストケースにそれを追加しましょう。
"make test" を実行することにより、正しいスクリプト Mytest.t を実行して
適切なバージョンのエクステンションを使うことが保証されます。
たくさんのテストケースがあるのなら、
"t" という名前のディレクトリに、".t" の拡張子でテストファイルを保存します。
"make test" を実行すると、これらのテストファイル全てが実行されます。
三番目の例は、入力として引数を一つとってその値を丸めてからその結果を 引数にセットするというものです。
以下の行を Mytest.xs の末尾に追加します:
void
round(arg)
double arg
CODE:
if (arg > 0.0) {
arg = floor(arg + 0.5);
} else if (arg < 0.0) {
arg = ceil(arg - 0.5);
} else {
arg = 0.0;
}
OUTPUT:
arg
Makefile.pl というファイルを編集し、対応する行を以下に示すように してください。
'LIBS' => ['-lm'], # e.g., '-lm'
Makefile を生成してから make を実行します。 Mytest.t のテスト番号を "9" に変更し、さらに以下のテストを追加します。
$i = -1.5; &Mytest::round($i); is( $i, -2.0 );
$i = -1.1; &Mytest::round($i); is( $i, -1.0 );
$i = 0.0; &Mytest::round($i); is( $i, 0.0 );
$i = 0.5; &Mytest::round($i); is( $i, 1.0 );
$i = 1.2; &Mytest::round($i); is( $i, 1.0 );
"make test" を実行します。
ここで、九つのテストすべてで ok と出力されるはずです。
これらの新しいテストケースでは、丸めるために渡される引数が スカラ変数であることに注目してください。 定数やリテラルを丸めたらどうなるだろうか、という疑問を持ったかもしれません。 何が起きるかを確かめるために、以下の行を Mytest.t に一時的に 追加してください。
&Mytest::round(3);
"make test" を実行すると、Perl は致命的エラーを起こして
終了してしまいます。
Perl は、定数値を変更させないのです!
Makefile.pl に対する変更をしました。 この場合、エクステンションの共有ライブラリとリンクすべき追加のライブラリ (今回の場合は数学ライブラリ libm)を指定します。 後で、ライブラリにあるすべてのルーチンを呼び出すことのできる XSUB の 書き方について説明します。
関数の値が関数の戻り値として返されるのではなく、関数に渡された 変数の値を変更することで返されます。 round の返り値の型は "void" であると推測したかもしれません。
関数の戻り値と名前を宣言した後の行に XSUB に渡すパラメータを指定できます。 各パラメータ行は(省略可能な)空白で始まり、(省略可能な)終端する セミコロンがあります。
出力パラメータは関数の最後、OUTPUT: 指示子の直後に置きます。 RETVAL を使うことで、Perl に XSUB 関数の戻り値を返したいという意志を 伝えます。 例 3 では、「返り値」を私たちが渡した元の変数に入れてほしいので、 (RETVAL でなく) その変数を OUTPUT: セクションに並べたのです。
xsubpp プログラムは .xs ファイルにある XS コードを取り、それを C に 翻訳しその結果を .c という拡張子のファイルに出力します。 変換された C コードは Perl の中にある C の関数を使うように作られます。
xsubpp プログラムは Perl のデータ型(スカラー、配列、など)から C のデータ型(int, char, など)に変換する規則を使います。 これらのルールは typemap ファイル ($PERLLIB/ExtUtils/typemap)に 格納されます。 このファイルは三つの部分に分けられます。
最初のセクションは様々な C のデータ型を、様々な Perl の型にいくらか対応する 名前にマッピングするものです。 二番目のセクションは入力パラメータを扱うために xsubpp が使用する C コードからなります。 三番目のセクションは出力パラメータに対して xsubpp が使用する C コードからなります。
さあ、私たちのエクステンションのために作られた .c ファイルの一部を 見てみましょう。 ファイル名は Mytest.c です:
XS(XS_Mytest_round)
{
dXSARGS;
if (items != 1)
Perl_croak(aTHX_ "Usage: Mytest::round(arg)");
PERL_UNUSED_VAR(cv); /* -W */
{
double arg = (double)SvNV(ST(0)); /* XXXXX */
if (arg > 0.0) {
arg = floor(arg + 0.5);
} else if (arg < 0.0) {
arg = ceil(arg - 0.5);
} else {
arg = 0.0;
}
sv_setnv(ST(0), (double)arg); /* XXXXX */
SvSETMAGIC(ST(0));
}
XSRETURN_EMPTY;
}
"XXXXX" というコメントが付けられた二つの行に注意してください。 typemap ファイルの最初のセクションを確かめれば、doublesT_DOUBLE という型で あることがわかるでしょう。 INPUT セクションでは T_DOUBLE である引数は、SvNv というルーチンを 呼び出すことによって変数が割り当てられ、その後で double に キャストされてから引数である変数に代入されます。 同様に、OUTPUT セクションでは一度引数が最終的な値を持てば、それは 呼び出された関数に返すために関数 sv_setnv に渡されます。 これら二つの関数は perlguts で説明されています。 引数スタックにあるセクションの "ST(0)" の意味は後で説明します。
一般的にいって、例 3 にあるように入力引数を書き換えるような エクステンションを作ることはよくありません。 代わりに、おそらくは複数の値を配列で返して、呼び出し元にそれを扱わせるように するべきです(これは後の例で行います)。 しかしながら、すでにある入力パラメータを書き換えるような C のルーチンの 呼び出しにより良く適応するために、この振る舞いが許されているのです。 次の例では、これをどう行うかを説明します。
この例で、すでにある C ライブラリとやりとりするような XSUB の記述を 始めます。 これを始めるために、独自の小さなライブラリを作ります。 それから .pm と .xs のための h2xs を記述します。
ディレクトリ Mytest と同じレベルに、Mytest2 ディレクトリを新たに 作ります。 Mytest2 ディレクトリで、mylib という別のディレクトリを作成し、そこに cd します。
ここで、テスト用のライブラリを生成するための幾つかのファイルを作ります。 こういったファイルには、C ソースファイルとヘッダーファイルが含まれます。 また、このディレクトリで Makefile.PL も作ります。 その後で、Mytest2 のレベルで make を実行することにより自動的に Makefile.PL が実行され、その結果 Makefile が作成されます。
ディレクトリ mylib で、以下のような内容の mylib.h というファイルを 作成します。
#define TESTVAL 4
extern double foo(int, long, const char*);
#include <stdlib.h>
#include "./mylib.h"
#include <stdlib.h>
#include "./mylib.h"
double
foo(int a, long b, const char *c)
{
return (a + b + atof(c) + TESTVAL);
}
use ExtUtils::MakeMaker;
$Verbose = 1;
WriteMakefile(
NAME => 'Mytest2::mylib',
SKIP => [qw(all static static_lib dynamic dynamic_lib)],
clean => {'FILES' => 'libmylib$(LIB_EXT)'},
);
use ExtUtils::MakeMaker;
$Verbose = 1;
WriteMakefile(
NAME => 'Mytest2::mylib',
SKIP => [qw(all static static_lib dynamic dynamic_lib)],
clean => {'FILES' => 'libmylib$(LIB_EXT)'},
);
sub MY::top_targets {
'
all :: static
pure_all :: static
static :: libmylib$(LIB_EXT)
libmylib$(LIB_EXT): $(O_FILES)
$(AR) cr libmylib$(LIB_EXT) $(O_FILES)
$(RANLIB) libmylib$(LIB_EXT)
';
}
"$(AR)" と "$(RANLIB)" で始まる行では空白ではなくタブを使っていることを 確認してください。 また、Win32 システムでは、$(AR) の "cr" 引数は不要であることが 報告されています。
ここでトップレベルの Mytest2 というファイルを作成します。 Mytest2 ディレクトリ に変更して、以下のコマンドを実行します。
% h2xs -O -n Mytest2 ./Mytest2/mylib/mylib.h
これにより、Mytest2 を上書きするという警告が出ますが、気にすることは ありません。 私たちのファイルは Mytest2/mylib にありますが、さわりません。
h2xs が生成した通常の Makefile.PL は mylib ディレクトリに関してなにも 知りません。 私たちはそういったサブディレクトリがあり、そこにライブラリを作成すると いうことを教えなければなりません。 引数 MYEXTLIB を WriteMakefile 呼び出しに追加して、次のような感じに しましょう:
WriteMakefile(
'NAME' => 'Mytest2',
'VERSION_FROM' => 'Mytest2.pm', # finds $VERSION
'LIBS' => [''], # e.g., '-lm'
'DEFINE' => '', # e.g., '-DHAVE_SOMETHING'
'INC' => '', # e.g., '-I/usr/include/other'
'MYEXTLIB' => 'mylib/libmylib$(LIB_EXT)',
);
それから、末尾にサブルーチンを付け加えます(これは既に存在するサブルーチンを 上書きします)。 "cd" で始まる行のインデントにタブ文字を使うことを忘れないでください!
sub MY::postamble {
'
$(MYEXTLIB): mylib/Makefile
cd mylib && $(MAKE) $(PASSTHRU)
';
}
また、ファイル MANIFEST を私たちのエクステンションの内容を反映するように 修正しましょう。 "mylib" という単一の行を以下の三行で置き換えます。
mylib/Makefile.PL
mylib/mylib.c
mylib/mylib.h
私たちの名前空間を奇麗で、汚染されていない状態に保つために .pm ファイルを
編集して、@EXPORT を設定している行を @EXPORT_OK に変更します。
最後に .xs ファイルで、#include の行を編集します。
#include "mylib/mylib.h"
さらに、以下の関数定義を .xs ファイルの末尾に追加します。
double
foo(a,b,c)
int a
long b
const char * c
OUTPUT:
RETVAL
ここで、デフォルトの Perl は今のところ const char * という型をサポートして いないので、typemap ファイルを作成する必要があります。 Mytest2 ディレクトリに typemap と呼ばれるファイルを作成し、それを以下の 内容にします:
const char * T_PV
次にトップレベルの Makefile.PL で perl を実行します。 mylib ディレクトリにある Makefile も作られるということに注意してください。 make を実行し、それにより mylib ディレクトリに cd し、そこで make が 実行されるのを確認します。
Mytest2.t スクリプトを編集して、テストの数を "4" に変更して、 スクリプトの末尾に以下の行を追加します。
is( &Mytest2::foo(1, 2, "Hello, world!"), 7 );
is( &Mytest2::foo(1, 2, "0.0"), 7 );
ok( abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 );
(浮動小数点数の比較を行うとき、等しいということをチェックしないことが 最良なのですが、代わりに予想される値と実際の結果の差がある値 (εと呼ばれます)、この場合では 0.01 以内かを調べています)
"make test" を実行すれば、すべてがうまくいくはずです。
Mytest2::mylib エクステンションにテストがないという警告が出ますが、
無視して構いません。
先の例とは違って、今回は実際のインクルードファイルに対して h2xs を 実行しました。 これは .pm ファイルと .xs ファイルの両方に対して幾つかの追加されるものを もたらします。
.xs ファイルには、現在のところ絶対パスで mylib.h ヘッダーファイルを 指定する #include 指示子があります。 これを相対パスに変更することで、もし望むならエクステンションの ディレクトリを移動できるようにします。
.xs ファイルに追加された C のコードがあります。
constant ルーチンの目的は、ヘッダーファイルで #define されている値を
Perl スクリプト(この場合は、&Mytest2::TESTVAL の呼び出しによります)に
よってアクセスできるようにすることです。
同様に constant ルーチンを呼び出すための XS コードがあります。
.pm ファイルは元々は配列 @EXPORT にある TESTVAL の名前を
エクスポートします。
これは名前を壊す可能性があります。
よい経験則は #define が C のルーチンでのみ使われてユーザーからは
使われないのであれば、それを配列 @EXPORT から取り除いたほうが
良いというものです。
もう一つは、変数の完全修飾名を使うことを使うのが気にならないのであれば、
配列 @EXPORT にある要素のほとんどすべてを配列 @EXPORT_OK に
移すことができます。
インクルードファイルに #include 指示子あるのであれば、それらは h2xs によって処理されません。 現時点ではこれを正しく処理するのに良い解決策はありません。
私たちはすでにサブディレクトリ mylib で作成したライブラリについての
指示を Perl にしています。
ここで要求されているのは、変数 MYEXTLIB を WriteMakefile の呼び出しに
追加し、postamble サブルーチンを目的のディレクトリへ cd して make を
実行するようにすることだけです。
ライブラリのための Makefile.PL は多少複雑にはなりますが、
それほどでもありません。
このコードは単純に作成すべきライブラリが静的ライブラリ(動的ロード可能
ライブラリと反対のもの)であることを指定し、ライブラリを作成するための
コマンドを提供します。
例 4 の .xs ファイルにはいくつか新しい要素を含んでいます。 これらの要素の意味を理解するために、以下の行に注目してください
MODULE = Mytest2 PACKAGE = Mytest2
この行以前の全てはインクルードするヘッダおよび便利な関数を定義した プレーンな C コードです。 この部分では、組み込みの POD 文書が読み飛ばされる(perlpod を 参照してください)ことを除いては何の変換は行われず、そのまま出力 C ファイルが 出力されます。
この行以降の全ては XSUB 関数の記述です。 これらの記述は、関数を Perl 呼び出し規則を使って実装し、関数が Perl インタプリタから見えるように、xsubpp が C コードに変換します。
constant 関数には特別な注意を払ってください。
この名前は生成された .xs ファイルに 2 回現れます:
1 回目は最初の部分に static C 関数として、2 回目は 2 番目の部分に、
この static C 関数への XSUB インターフェースが定義されたときです。
これは .xs ファイルではかなり典型的です: 普通 .xs ファイルは既にある C 関数へのインターフェースを提供します。 それからこの C 関数はどこか(外部ライブラリか、.xs ファイルの最初の部分)で 定義され、この関数への Perl インターフェース(つまり「Perl の糊」)が .xs ファイルの 2 番目の部分に記述されます。 例 1, 例 2, 例 3 の状況、 つまり全ての動作が「Perl の糊」の内側で行われるときは、 規則ではなく何らかの例外があります。
例 4 で、.xs ファイルの 2 番目の部分には、以下の XSUB の 記述を含んでいます:
double
foo(a,b,c)
int a
long b
const char * c
OUTPUT:
RETVAL
例 1, 例 2, 例 3 と比較して、この記述は
Perl 関数 foo() の呼び出しに何が起きているのかの実際の コード は
含んでいません。
ここで何が起きているのかを理解するために、この XSUB に CODE セクションを
追加できます:
double
foo(a,b,c)
int a
long b
const char * c
CODE:
RETVAL = foo(a,b,c);
OUTPUT:
RETVAL
しかし、これら 2 つの XSUB はほとんど同じ C コードを生成します:
xsubpp コンパイラは、XSUB の記述の最初の 2 行から
CODE: セクションを見つけ出すことができるぐらい賢いです。
OUTPUT: セクションについてはどうでしょう?
実際、これは全く同じです!
CODE: セクションや PPCODE: セクションが指定されない限り、
OUTPUT: セクションも同様に削除でき、同様に OUTPUT セクションを
自動生成します。
従って、XSUB を以下のように省略できます:
double
foo(a,b,c)
int a
long b
const char * c
同じことを 例 2 の XSUB:
int
is_even(input)
int input
CODE:
RETVAL = (input % 2 == 0);
OUTPUT:
RETVAL
で出来るでしょうか?
これをするためには、C 関数 int is_even(int input) を定義する
必要があります。
.xs ファイルの解剖 で見たように、この定義に適切な場所は .xs ファイルの
最初の部分です。
実際、C 関数
int
is_even(int arg)
{
return (arg % 2 == 0);
}
というのはおそらくここではやりすぎです。
#define と同じぐらい単純なこともできます:
#define is_even(arg) ((arg) % 2 == 0)
.xs ファイルの最初の部分にこれを入れた後、 「Perl の糊」の部分は以下のように単純です
int
is_even(input)
int input
実際の動作の部分から糊の部分を分離する技術は明らかなトレードオフです: もし Perl インターフェースをしようとすると、コードの 2 箇所を変更する 必要があります。 しかし、これは多くの乱雑なものを取り除き、実際の動作の部分を Perl 呼び出し 規則の特異性から独立させます。 (実際のところ、上述の記述には Perl 固有のものはなく、異なるバージョンの xsubpp はこれを TCL の糊や Python の糊にも変換できるかもしれません。)
例 4 を補完するために、私たちは世界で最もクリーンというわけではないであろう 現実のライブラリのシミュレートをするための簡単な方法があります。 私たちは xsubpp コンパイラに渡す引数についての議論を 続けなければなりません。
.xs ファイルでルーチンへの引数を指定したとき、あなたはそれぞれの 引数がリストアップされた三つの情報ブロックを渡しているでしょう。 最初のブロックは、引数の相対的な順序(一番目、二番目、…)です。 二番目のブロックは引数の型で、引数の型宣言からなります。 三番目のブロックは、引数がライブラリ関数を呼び出すときに使われる引数の 呼び出し規約です。
Perl は関数に引数を参照渡ししますが、C は引数を値渡しします; 「引数」の 一つのデータを修正する C 関数を実装するには、この C 関数の実際の引数は そのデータへのポインタになります。 従って、2 つの C 関数宣言:
int string_length(char *s);
int upper_case_char(char *cp);
は完全に異なった意味を持ちます:
前者は s で示された char の配列を検査します; 後者は直ちに cp を
デリファレンスして、*cp だけを操作します(返り値は成功を示すものとして
使われます)。
Perl からはこれらの関数は全く異なった方法で使います。
& による引数の前に * を置き換えることで、この情報を xsubpp に
伝えられます。
& は、引数がアドレスでライブラリ関数に渡されることを意味します。
上記の 2 つの関数は以下のように XSUB 化できます
int
string_length(s)
char * s
int
upper_case_char(cp)
char &cp
例として、次のものを考えます:
int
foo(a,b)
char &a
char * b
最初の Perl の引数はこの関数では char として扱われ、変数 a に代入され、 そしてそのアドレスは関数 foo に渡されます。 二番目の Perl の引数は文字列へのポインターとして扱われ、変数 b へ 代入されます。 b の 値 も関数 foo へ渡されます。 xsubpp が生成する関数 foo への実際の呼び出しは次のようになります。
foo(&a, b);
xsubpp は以下の関数引数リストを同じものと解析します:
char &a
char&a
char & a
しかしながらわかりやすくするために、 "&" に変数名を続けて変数の型からは 離しておくことと、 "*" を型名に近づけるが変数名からは離す(前述した foo の 呼び出しのように)ということをお勧めします。 これを行うことで、実際に C の関数に渡されるがなんなのかを簡単に 理解できます -- これは "last column" にあるものでしょう。
可能ならば、関数に(自分が望む)変数の型を渡すことに挑戦して苦労したほうが 良いでしょう。 長い目で見ればそれによって多くのトラブルを避けることになります。
例 1 以外の このチュートリアルで作成した C コードを見たのならば、
たくさんのST(n) (n は通常は 0)に対する参照に気がついたことでしょう。
"ST" は実際には引数スタック上の n 番目の引数を指し示すマクロです。
従って ST(0) はスタック上の最初の引数なので、XSUB に渡される最初の
引数であり、ST(1) は二番目の引数となります。
.xs ファイル中で XSUB に対する引数をリストアップしたとき、それは引数 スタックの対応する引数を xsubpp に指定するということです(例えば、 リストの最初にあれば第一引数、二番目なら第二引数ということ)。 関数が期待するのと同じ順番でリストアップしなければ、思いがけない 災害を招くことになります。
引数スタックの実際の値は渡された値へのポインタです。
引数が OUTPUT の値として挙げられている場合、スタック上の対応する値
(例えば、最初の引数なら ST(0)) が変更されます。
例 3 で生成された C コードを見ることでこれを検証できます。
round() XSUB ルーチンのコードは以下のように見える行を含んでいます:
double arg = (double)SvNV(ST(0));
/* Round the contents of the variable arg */
sv_setnv(ST(0), (double)arg);
引数変数は、まず ST(0) の値から取られるものにセットされ、その後ルーチンの
最後に ST(0) に書き戻されます。
XSUB は単なるスカラではなく、リストを返すこともできます。
これはスタック値 ST(0), ST(1) などを微妙に違う方法で操作することによって
行う必要があります。
詳しくは perlxs を参照してください。
XSUB はまた、Perl 関数引数から C 関数引数への自動変換を回避することも
できます。
詳しくは perlxs を参照してください。
自動変換が行われる場合でも ST(i) を検査することでの手動変換を好む
人々もいて、これにより XSUB 呼び出しのロジックがよりきれいになると
主張しています。
XSUB における「Perl の糊」と「実働部隊」の完全な分離に関する似たような
トレードオフに関して、太った部分を XSUB の外に出す と
比較してください。
専門家はこれらの慣用法について主張する一方、Perl の内部に関する初心者は Perl 内部に固有のものを可能な限り小さくする方法を好みます; これはつまり 太った部分を XSUB の外に出す のような、自動変換と自動呼び出し 生成です。 この手法には、XSUB 作者を Perl API の将来の変更から守るという追加の利点も あります。
Perlとあなたのエクステンションとの間のインターフェースをより簡単に、 より理解しやすくするのを助けるためにメソッドやサブルーチンを 作りたいと思う事があるかもしれません。 こういったルーチンは .pm ファイルに置くのが良いです。 これがエクステンション自身がロードされたときロードされるにしろ、 サブルーチン定義が置かれている. pm ファイルに依存する呼び出しのときのみ ロードするにしろ、自動的にロードが行われます。 追加のサブルーチンを保管して読み込むもう一つの方法としては AutoLoader を参考にすることもできます。
あなたのエクステンションに関するドキュメントがないということについて、 あなたは何の言い訳もできません。 ドキュメントは .pm ファイルに属します。 このファイルは pod2man に送り込まれ、埋め込まれたドキュメントが man ページフォーマットに変換され、それから blib ディレクトリに置かれます。 このドキュメントは、エクステンションがインストールされるときに Perl の man ページディレクトリにもコピーされます。
あなたは .pm ファイルにあるドキュメントと Perl コードをまき散らすことが あるかもしれません。 事実、あなたがメソッドを autoload しようとするならば、.pm ファイルの中に あるコメントで説明されているようにこれを行わねばなりません。
pod フォーマットについてのより詳しい情報は perlpod を参照してください。
あなたの作ったエクステンションが完成し、かつすべてのテストに合格すれば、 それを実に単純なやりかたでインストールします。 ただ単に "make install" と実行するだけです。 Perl がインストールされたディレクトリに対する書き込み権限が持っている 必要がありますが、あるいは、あなたのシステム管理者にあなたの make を 実行するようお願いする必要があるでしょう。
別の方法として、"make install" の後ろに (あるいはおかしな make を使っている 場合は "make" と "install" の間に)"PREFIX=/destination/directory" と 書くことで、エクステンションのファイルを置く正確なディレクトリを 指定できます。 これは、最終的に複数のシステムに配布されるエクステンションをビルドしている 場合にとても有用です。 その後単に出力先のディレクトリのファイルをアーカイブして、目的のシステムに 配布します。
この例では、引数スタックにさらなる作業をします。 前の例では全て、単一の値を返すものだけです。 ここでは、配列を返すエクステンションを作ります。
このエクステンションはとても Unix 指向です(struct statfs と statfs システムコール)。 もし Unix システム以外で実行するなら、statfs を複数の値を返す別の関数に 置き換えるか、呼び出し元に返す値をハードコーディングする(しかしこれは エラーの場合をテストするのが少し難しくなります)か、あるいは単に この例を実行しないということもできます。 もし XSUB を変更したなら、テストケースも変更にあわせて確実に 修正してください。
Mytest ディレクトリに戻って、Mytest.xs の末尾に以下のコードを追加します:
void
statfs(path)
char * path
INIT:
int i;
struct statfs buf;
PPCODE:
i = statfs(path, &buf);
if (i == 0) {
XPUSHs(sv_2mortal(newSVnv(buf.f_bavail)));
XPUSHs(sv_2mortal(newSVnv(buf.f_bfree)));
XPUSHs(sv_2mortal(newSVnv(buf.f_blocks)));
XPUSHs(sv_2mortal(newSVnv(buf.f_bsize)));
XPUSHs(sv_2mortal(newSVnv(buf.f_ffree)));
XPUSHs(sv_2mortal(newSVnv(buf.f_files)));
XPUSHs(sv_2mortal(newSVnv(buf.f_type)));
} else {
XPUSHs(sv_2mortal(newSVnv(errno)));
}
また、.xs ファイルの先頭、"XSUB.h" をインクルードした直後に、以下のコードを 追加する必要があります:
#include <sys/vfs.h>
また、以下のコードを Mytest.t に追加する一方、"9" のテストを "11" に 増やします:
@a = &Mytest::statfs("/blech");
ok( scalar(@a) == 1 && $a[0] == 2 );
@a = &Mytest::statfs("/");
is( scalar(@a), 7 );
この例はいくつかの全く新しい概念を追加します。 一回に一つずつやります。
INIT: 指示子は、引数スタックがデコードされた直後に置かれるコードを含みます。
C では関数内の任の市での変数宣言を許していないので、
これは普通 XSUB によって必要なローカル変数を宣言するための最善の方法です。
(代替案としては、PPCODE: セクション全体を中かっこで囲って、それらの
宣言を先頭に置くこともできます。)
このルーチンはまた、statfs の呼び出しが成功か失敗かに依存して、異なった 数の値を返します。 エラーの場合は、エラー番号が単一の要素の配列として返されます。 呼び出しが成功した場合は、9 要素の配列が返されます。 この関数には引数が 1 つだけ渡されるので、返す 9 つの値を保持するために スタックに空きを作る必要があります。
これを、CODE: 指示子ではなく PPCODE: 指示子を使うことで行います。 これは、引数スタックに置かれる返り値の管理を自分自身で行うことを xsubpp に知らせます。
呼び出し元に返す値を置くための場所がスタック上にほしい時、 "XPUSH" で始まる一連のマクロを使います。 これには、スタック上に整数、符号なし整数、double、文字列、Perl スカラを 置くための 5 種類があります。 この例では、スタック上に Perl スカラをおきます。 (実際のところ、これは複数の値を返すときに使える唯一のマクロです。)
XPUSH* マクロは、返り値スタックがオーバーランすることを防ぐために、自動的に 返り値スタックを拡張します。 呼び出しプログラムから見えてほしい順番にスタックに値をプッシュします。
XSUB の返り値スタックにプッシュされた値は実際には揮発性の SV です。 これは揮発性なので、一旦呼び出しプログラムによって値がコピーされれば、 返り値を保持している SV は開放できます。 もしこれらが揮発性でないなら、XSUB ルーチンから返った後も存在し続けますが、 アクセスできなくなります。 これはメモリリークです。
もしコードサイズではなく性能に興味があるのなら、成功時には
XPUSHs ではなく PUSHs を使って、返り値をプッシュする前に予めスタックを
拡張しておきます:
EXTEND(SP, 7);
トレードオフは、予め返り値の数を計算しておく必要があることです (しかしスタックを余分に拡張しても、典型的にはメモリ消費以外にはなんの問題も ありません)。
同様に、失敗時にはスタックを 拡張せずに PUSHs を使えます:
Perl 関数のリファレンスはスタックで XSUB に渡されるので、
スタックは 常に 一つの返り値を返すには十分な大きさがあります。
この例では、入力パラメータとして配列へのリファレンスを受け付け、ハッシュの 配列へのリファレンスを返します。 ここでは、複雑な Perl データ型を XSUB から操作する方法を示します。
このエクステンションはやや不自然です。 これは以前の例のコードを基礎にしています。 これは statfs 関数を複数呼び出し、入力としてファイル名の配列への リファレンスを受け付けて、それぞれのファイルシステムのデータを含む ハッシュの配列へのリファレンスを返します。
Mytest ディレクトリに戻って、Mytest.xs の末尾に以下のコードを追加します:
SV *
multi_statfs(paths)
SV * paths
INIT:
AV * results;
I32 numpaths = 0;
int i, n;
struct statfs buf;
if ((!SvROK(paths))
|| (SvTYPE(SvRV(paths)) != SVt_PVAV)
|| ((numpaths = av_len((AV *)SvRV(paths))) < 0))
{
XSRETURN_UNDEF;
}
results = (AV *)sv_2mortal((SV *)newAV());
CODE:
for (n = 0; n <= numpaths; n++) {
HV * rh;
STRLEN l;
char * fn = SvPV(*av_fetch((AV *)SvRV(paths), n, 0), l);
i = statfs(fn, &buf);
if (i != 0) {
av_push(results, newSVnv(errno));
continue;
}
rh = (HV *)sv_2mortal((SV *)newHV());
hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0);
hv_store(rh, "f_bfree", 7, newSVnv(buf.f_bfree), 0);
hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0);
hv_store(rh, "f_bsize", 7, newSVnv(buf.f_bsize), 0);
hv_store(rh, "f_ffree", 7, newSVnv(buf.f_ffree), 0);
hv_store(rh, "f_files", 7, newSVnv(buf.f_files), 0);
hv_store(rh, "f_type", 6, newSVnv(buf.f_type), 0);
av_push(results, newRV((SV *)rh));
}
RETVAL = newRV((SV *)results);
OUTPUT:
RETVAL
また、以下のコードを Mytest.t に追加する一方、"11" のテストを "13" に増やします:
$results = Mytest::multi_statfs([ '/', '/blech' ]);
ok( ref $results->[0]) );
ok( ! ref $results->[1] );
ここでは後述するいくつかの新しい概念があります:
この関数は typemap を使いません。
代わりに、一つの SV* (スカラ) 引数を受け入れ、一つの SV* 値を返すように
定義して、これらのスカラをコード内で引き受けます。
一つの値だけを返すので、 PPCODE: 指示子は不要です - 代わりに、
CODE: と OUTPUT: の指示子を使います。
リファレンスを扱うとき、これを注意して扱うことが重要です。
INIT: ブロックはまず、SvROK が真を返すことろチェックします;
これをパスが正当なリファレンスであることを示しています。
それから、SvRV でパスをデリファレンスして、SvTYPE でその型を
調べることで、パスでリファレンスされているオブジェクトが配列であることを
検証します。
追加のテストとして、(配列が空の場合に -1 を返す)av_len 関数を使って、
パスでリファレンスされた配列が空でないことをチェックします。
XSRETURN_UNDEF マクロは、これら 3 つの条件のどれかが成立しないときに
XSUB を中断して未定義値を返すために使われます。
この XSUB でいくつかの配列を操作します。
配列は内部的に AV* ポインタで表現されていることに注意してください。
配列操作のための関数とマクロは Perl の関数と似ています: av_len は、
$#array と同様、AV* の最大の添え字を返します; av_fetch は添え字を
取って、配列から 1 つのスカラ値を取り出します; av_push はスカラ値を
配列の最後にスカラ値をプッシュし、もし必要なら自動的に配列を拡張します。
特に、入力配列から一度に 1 つだけパス名を読み込み、結果を出力配列に 同じ順序で保管します。 もし statfs が失敗すると、返り値配列にプッシュされる要素は失敗時の errno です。 しかし、statfs が成功すると、返り値配列にプッシュされる値は statfs 構造体の 情報を含むハッシュへのリファレンスです。
返り値スタックに関して、いくつの要素が返されるかは分かっているので、 データをプッシュする前に返り値配列を予め拡張しておくことが可能です (そして少し性能がよくなります):
av_extend(results, numpaths);
この関数では、hv_store を使ってキーに対して新しいスカラを保管するという、
1 つのハッシュ操作のみを行います。
ハッシュは HV* ポインタで表現されます。
配列と同様、XSUB からハッシュを操作する関数は、Perl から利用可能な機能と
鏡写しです。
詳しくは perlguts と perlapi を参照してください。
リファレンスを作るには、 newRV 関数を使います。
この場合(およびその他多くの場合)、AV* か HV* を SV* 型に
キャストできることに注意してください。
これにより、同じ関数で配列、ハッシュ、スカラのリファレンスを得ることが
できます。
反対に、 SvRV 関数は常に SV* を返すので、もしこれが(SvTYPE を
チェックして)スカラ以外の場合、適切な型にキャストする必要があります。
この時点で、xsubpp はほとんど何もしていません - Mytest.xs と Mytest.c との 差は最小限です。
引数の XPUSH と RETVAL のセットと返り値の配列への代入
$! をセットする
型グロブなどで、XS にファイルを渡すのは難しいと考えるかもしれません。 えっと、そうではありません。
標準 C ライブラリ関数 fputs() のラッパーが必要、という不思議な
理由があるとしましょう。
必要なものは以下のものだけです:
#define PERLIO_NOT_STDIO 0
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
#include <stdio.h>
int
fputs(s, stream)
char * s
FILE * stream
実際の作業は標準の typemap で行われます。
しかし、perlio 層で行われる素晴らしい機能全てを手放すことになります。
これは stdio 関数 fputs() を呼び出すので、それらについては何もしません。
標準 typemap は 3 種類の PerlIO * を提供します:
InputStream (T_IN), InOutStream (T_INOUT),
OutputStream (T_OUT) です。
生の PerlIO * は T_INOUT として扱われます。
コード中でこれが問題になる場合(なぜそうなり得るかは以下を
参照してください)、特定の名前の一つを #define や typedef して、
それを XS ファイルで引数や結果の型として使ってください。
perl 5.7 以前の標準 typemap には PerlIO * は含まれていませんが、 3 種類のストリームの種類があります。 PerlIO * を直接使うと、独自の typemap を提供しない限り、 後方互換ではありません。
perl から 来るストリームについて、主な違いは OutputStream が
出力 PerlIO * を得るということです - これはソケットの場合に違いとなります。
私たちの例と同様に…
perl に 渡されるストリームについて、新しいファイルハンドル
(つまり、新しいグロブへのリファレンス)が作成され、提供された PerlIO * と
結び付けられます。
もし PerlIO * の読み込み/書き込み状態が正しくない場合、ファイルハンドルが
使われたときにエラーや警告を受けることになります。
従って、もし PerlIO * を "w" としてオープンしたなら実際には
OutputStream であるべきですし、"r" としてオープンしたなら
InputStream であるべきです。
ここで、XS で perlio 層を使いたいとしましょう。
例のように、perlio の PerlIO_puts() 関数を使います。
XS ファイルの C の部分 (最初の MODULE 行の上) に以下のようにします
#define OutputStream PerlIO *
or
typedef PerlIO * OutputStream;
そして XS コードはこれです:
int
perlioputs(s, stream)
char * s
OutputStream stream
CODE:
RETVAL = PerlIO_puts(stream, s);
OUTPUT:
RETVAL
PerlIO_puts() は fputs() と比較する予約された引数を持っていて、
引数は同じままにしたいので、CODE セクションを使う必要があります。
これを完全に探索するために、PerlIO * に stdio の fputs() を使いたいです。
これは、perlio システムに stdio の FILE * を問い合わせる必要があります:
int
perliofputs(s, stream)
char * s
OutputStream stream
PREINIT:
FILE *fp = PerlIO_findFILE(stream);
CODE:
if (fp != (FILE*) 0) {
RETVAL = fputs(s, fp);
} else {
RETVAL = -1;
}
OUTPUT:
RETVAL
注意: PerlIO_findFILE() は stdio 層の層を検索します。
もしそれが見つからなければ、新しい stdio FILE を生成するために
PerlIO_exportFILE() を呼び出します。
新しい FILE が必要な場合にのみ PerlIO_exportFILE() を
呼び出すようにしてください。
これは呼び出し毎に新しいものを生成して新しい stdio 層にプッシュします。
従って、同じファイルに対して繰り返し呼び出さないでください。
PerlIO()_findFILE は、一度 PerlIO_exportFILE() で生成された stdio 層を
取り出します。
これは perlio システムにのみ適用されます。
5.7 以前のバージョンでは、PerlIO_exportFILE() は PerlIO_findFILE() と
等価です。
この文書の最初に触れたように、もしこれらの例のエクステンションで問題が あった場合、以下が参考になるかもしれません。
γバージョン以前のバージョン 5.002 では、例 1 にあるテスト スクリプトは正しく動作しません。 "use lib" という行を以下の様に変更する必要があります。
use lib './blib';
バージョン 5.002b1h 以前のバージョン 5.002 では、test.pl というファイルが h2xs によって自動生成されません。 これはテストスクリプトを実行するために、"make test" とすることが できないということです。 "use extension" という文の前に以下の行を追加する必要があります:
use lib './blib';
バージョン 5.000 および 5.001 では、上で示した行ではなく、以下に示した行を 使う必要があるでしょう。
BEGIN { unshift(@INC, "./blib") }
このドキュメントでは、"perl" という名前の実行ファイルが Perl のバージョン 5 であることを仮定しています。 Perl のバージョン 5 は "perl5" としてインストールされているシステムも あるかもしれません。
より詳しい情報は、perlguts, perlapi, perlxs, perlmod, perlpod を参照してください。
Jeff Okamoto <okamoto@corp.hp.com>
Dean Roehrich, Ilya Zakharevich, Andreas Koenig, Tim Bunce によるレビューと 助力を受けました。
PerlIO の素材は Lupe Christoph によって提供され、Nick Ing-Simmons によって 明確化されたものです。
Perl 5.8.x での h2xs に関しては Renee Baecker が変更しました。
2007/10/11