perlguts - Perl's Internal Functions Perlの内部関数
このドキュメントでは Perl の実行ファイルにある内部関数をいくつか 説明しています。完璧なものではありませんし、間違いも多いと思いま す。疑問点やコメントは後述する著者に対して行なってください。
Perl では、主となる三つのデータ型を扱うために三つの型定義を行な っています:
SV スカラー値 (Scalar Value)
AV 配列値 (Array Value)
HV ハッシュ値 (Hash Value)
それぞれの typedef には様々なデータ型を操作するための特別なルー チンが用意されています。
“IV”ってなに?
Perl では、整数でもポインタでも十分に入れることのできる特別な typedefである IV を使います。
Perlはまた、二つの特殊なtypedefであるI32とI16を使っています。こ れらはそれぞれ、常に最低32bit、16bitの長さを持っているものです。
SV は、1 つのコマンドで生成し、値をロードすることができます。ロ ードできる値の型には、整数 (IV)、倍精度 (NV)、文字列 (PV)、その 他のスカラー (SV) があります。
これらを行なう、六つのルーチンは:
SV* newSViv(IV);
SV* newSVnv(double);
SV* newSVpv(char*, int);
SV* newSVpvn(char*, int);
SV* newSVpvf(const char*, ...);
SV* newSVsv(SV*);
です。
「既に存在する」スカラーの値を変更するために 七つのル ーチンがあります: #八つの間違い?
void sv_setiv(SV*, IV);
void sv_setuv(SV*, UV);
void sv_setnv(SV*, double);
void sv_setpv(SV*, const char*);
void sv_setpvn(SV*, const char*, int)
void sv_setpvf(SV*, const char*, ...);
void sv_setpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
void sv_setsv(SV*, SV*);
代入すべき文字列の長さを sv_setpvn や newSVpv、あるいは
newSVpvを使って指定 することもできますし、sv_setpvを使ったりC<newSVpv>の第二引数 に0を指定することによって、Perl自身に文字列の長さを計算させるこ
ともできます。ただしPerlは、NUL文字で終了することに依存している
strlenを使って長さを計算しているということに注意してください。
sv_setpvfの引数はsprintfと同じように処理され、書式化された 出力が値となります。
sv_setpvfnはvsprintfと同じようなものですが、 可変引数リストに対するポインターか
SVの配列のアドレスと長さのいずれかを指定することができます。
最後の引数はブール値を指し示します。関数から返ってきたときに
これがtrueであれば、フォーマット文字列としてロカール固有の
情報が使われているのでその文字列の内容は信頼するできないことを
表わしています(perlsecを参照)。 ロカールに関する情報が重要でないのなら、
このポインターはNULLであってもかまいません。
この関数はフォーマットの長さを要求していることに注意してください。
sv_set*()関数群は“magic”を持っている値に対する
操作に対して充分に一般化されたものではありません。後述する
Magic Virtual Tablesを参照してください。
すべてのSVは、必須と言うわけではありませんがNULキャラクターで終 端されているべきです。この終端のNULが無かった場合、コアダンプし たり文字列を(文字列がNULで終端されていることを期待している)C関数 やシステムコールに渡すコードをおかしくする危険があります。Perl自 身の典型的な関数は、この理由により終端にNULを追加します。そうで あったとしても、あなたがSVに格納されている文字列をCの関数やシス テムコールに渡す時には十二分に気をつけるべきなのです。
SV が指し示す実際の値をアクセスするには、実際のスカラーの型を 制的に IV や倍精度や文字列にする
SvIV(SV*)
SvNV(SV*)
SvPV(SV*, STRLEN len)
というマクロを使うことができます。
SvPV マクロでは、返される文字列の長さは、変数 len に格納さ れます (これはマクロですから、&len としないでください)。も しデータの長さを気にしないのであれば、グローバル変数 PL_naか 型がSTRLENのローカル変数を使ってください。
PL_naを使うことは可能ですが効率は良くありません。
なぜならC<PL_na>はスレッド化したPerlではスレッドローカルな
領域にアクセスしなければならないからです。いずれの場合にも、
NULを含んでいたりNULで終端されていないような文字列を
扱うことができるということを忘れないでください．
同様に、CでSvPV(s, len), len)とすることが安全ではないことを
忘れないでください。これはあなたの使うコンパイラーによっては
うまくいきますが、いつでもそうだとは限らないのです。そこで、
こういったステートメントは以下のように分割します。
STRLEN len;
char * ptr;
ptr = SvPV(len);
foo(ptr, len);
単にスカラー値が真かどうかを知りたいだけならば、
SvTRUE(SV*)
を使うことができます。
Perl は、SV にもっとメモリを割り当てて欲しいときには自動的に文字 列を大きくしてくれますが、さらにメモリを割り当てさせることが必要 であれば
SvGROW(SV*, STRLEN newlen)
というマクロが使えます。もし必要なら、このマクロが sv_growを 呼びます。SvGROW は SV に割り当てたメモリを増やすだけで、減ら すことはできないということと、終端のNULの分のバイトが自動的に加 算されない(perl自身の文字列関数は 大概 SvGROW(sv, len + 1) としています)ということに注意してください。
手元にある SV の、 Perl から見たデータの種類を知りたいときには、 その SV の型をチェックするのに
SvIOK(SV*)
SvNOK(SV*)
SvPOK(SV*)
というマクロを使うことができます。
SV に納められた文字列の現在の長さを取得したり設定したりするのに は以下のマクロが使えます。
SvCUR(SV*)
SvCUR_set(SV*, I32 val)
同様に、SVに格納されている文字列の終端へのポインターを以下のマク ロを使って得ることができます。
SvEND(SV*)
ただし、これらは SvPOK() が真のときだけ有効だということに気を つけてください。
SV*に格納されている文字列の末尾になにかを追加したいときに以下 のような関数が使えます。
void sv_catpv(SV*, char*);
void sv_catpvn(SV*, char*, STRLEN);
void sv_catpvf(SV*, const char*, ...);
void sv_catpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
void sv_catsv(SV*, SV*);
最初の関数はstrlenを使って追加する文字列の長さを計算します。
二番目の関数では、関数を使用する人が文字列の長さを指定します。三
番目の関数はその引数をC<sprintf>の様に処理し、整形された結果を追 加します。 四番目の関数はvsprintfのように動作します。 va_list引数の代わりに、SVの配列のアドレスと長さを指定することが
できます。 五番目の関数は最初のSVにある文字列を二番目のSVにある文
字列で拡張します。また、この関数は二番目のSVを強制的に文字列とし
て解釈します。
sv_cat*()関数群は“magic”を持っている値に対する
操作に対して充分に一般化されたものではありません。後述する
Magic Virtual Tablesを参照してください。
スカラー変数の名前がわかれば、その SV へのポインタは
SV* perl_get_sv("package::varname", FALSE);
を使って得ることができます。その変数が存在しない場合には NULL が返さ れます。
その変数 (もしくは他の任意の SV) が、実際に定義されているか を知りたいならば、
SvOK(SV*)
スカラーの undef 値は、PL_sv_undef という SV のインスタンスに納めら れています。そのアドレスは、SV* が必要とされるところで使用 することができます。
ブール値の真と偽を表わす、PL_sv_yes や PL_sv_no という値もあります。 PL_sv_undef と同様に、これらのアドレスも SV* が必要なところで 使うことができます。
(SV *0) と &PL_sv_undef が同じであると考えて、だまされてはいけ
ません。次のようなコードを見てください:
SV* sv = (SV*) 0;
if (I-am-to-return-a-real-value) {
sv = sv_2mortal(newSViv(42));
}
sv_setsv(ST(0), sv);
このコードは、実値を返さなければならないときには、(値として42 を 持つ) 新しい SV を返そうとし、さもなくば undef を返そうとします。 ですが、どこかの行でナルポインタを返して、セグメントバイオレーシ ョンが起こるか、何かおかしな結果になってしまいます。最初の行の 0 を &PL_sv_undef に変えれば、すべてがうまくいきます。
生成した SV を解放するためには、SvREFCNT_dec(SV*) を呼びます。 普通は、この呼び出しは必要ありません。 Reference Counts and Mortalityを参照してください。
SVに実際に格納されているものは何ですか?
自分で保持しているスカラーの型を決定する通常の方法は、マクロC<Sv*OK> を使うものでした。スカラーは数値にも文字列にもなり得ますから、普通、
これらのマクロはいつも真を返します。そしてSv*V マクロを呼ぶことで、
文字列から整数/倍精度、整数/倍精度から文字列への変換を行ないます。
もし、本当に SV にあるのが整数か、倍精度か、文字列ポインタか を知りたいのであれば、
SvIOKp(SV*)
SvNOKp(SV*)
SvPOKp(SV*)
というマクロを代わりに使うことができます。これらのマクロは、実際 に SV に入っているものが整数か、倍精度か、文字列ポインタかを教え てくれます。
しかし一般的には、Sv*V マクロを使うだけにした方が良いでしょう。
AV を生成して値を設定するのには、二つの方法があります。最初の方 法は、単に空の AV を作るものです:
AV* newAV();
ふたつめの方法は、AV を生成した上で、初期値として SV の値を 入れます:
AV* av_make(I32 num, SV **ptr);
二番目の引数は num 個の SV* の配列を指しています。AVが生成されて しまえば、SVは(それを望むのなら)破棄することができます。
いったんAV が生成されると、AV に対して、
void av_push(AV*, SV*);
SV* av_pop(AV*);
SV* av_shift(AV*);
void av_unshift(AV*, I32 num);
といった操作が行えます。これらは、av_unshift を除いては、お馴 染みの演算でしょう。av_unshift は、配列の先頭に num個の
undef 値の要素を付け加えます。その後で、(後述する)av_store
を使って新しい要素に値を代入しなければなりません。
他にもいくつか関数があります:
I32 av_len(AV*);
SV** av_fetch(AV*, I32 key, I32 lval);
SV** av_store(AV*, I32 key, SV* val);
関数C<av_len>は配列における最高位の添え字を(ちょうどPerlの$#array
と同じように)返します。もし配列が空であれば、-1を返します。関数
av_fetchは添え字C<key>の位置にある値を返しますが、lvalが非 ゼロであれば、av_fetchはその位置にundefを格納しようとします。 関数 av_storeは添え字C<key>の位置に値valを格納し、valの 参照カウントをインクリメントしません。従って、呼び出し側はこの振
る舞いに注意して対処し、av_storeがNULLを返した場合には、メモ
リーリークを防ぐために参照カウントのデクリメントを行う必要がある でしょう。av_fetchとav_storeの両方ともがその戻り値として
SV*ではなく、SV**を返すということに注意してください。
void av_clear(AV*);
void av_undef(AV*);
void av_extend(AV*, I32 key);
関数 av_clearは、配列AV*にあるすべての要素を削除しますが、配
列自身の削除は行いません。関数 av_undefは配列にあるすべての要 素に加え、配列自身の削除も行います。関数 av_extendは配列を
key+1要素だけ拡張します。key+1が配列のその時点での長さより短け れば、何も行なわれません。
配列変数の名前がわかっているのであれば、次のようにしてその配列に 対応するAVへのポインターを得ることができます。
AV* perl_get_av("package::varname", FALSE);
これは変数が存在していない場合にはNULLを返します。
tieされた配列における配列アクセス関数の使い方についての詳細は Understanding the Magic of Tied Hashes and Arrays を参照して ください。
HV を生成するには、
HV* newHV();
というルーチンを使います。いったんHV が生成されると HV に対して、
SV** hv_store(HV*, char* key, U32 klen, SV* val, U32 hash);
SV** hv_fetch(HV*, char* key, U32 klen, I32 lval);
という操作が行えます。引数 klen は、渡される key の長さです (Perlにキーの長さを計算させるために、klen>の値として0を渡すこ とはできないということに注意してください)。引数 val は、設定 されるスカラーへの SV ポインタを入れ、hash は、あらかじめ計算し
たハッシュ値 (hv_store に計算させる場合には、ゼロ) です。引数
lval で、このフェッチ操作が実はストア操作の一部であるかどうか
を示します。ストア操作であれば、新たなundefind valueが与えられた
キーを伴ってHVに追加され、hv_fetchはその値が既に存在していた かのようにリターンします。
hv_store や hv_fetch は、SV** を返すもので、SV* では ないことに注意してください。スカラー値をアクセスするには、まず戻 り値の参照外し(dereference)をする必要があります。しかし、その前 に返却値が NULLでないことを確認すべきです。
ハッシュテーブルのエントリが存在するかをチェックし、削除を行う 関数があります。
bool hv_exists(HV*, char* key, U32 klen);
SV* hv_delete(HV*, char* key, U32 klen, I32 flags);
flagにG_DISCARDフラグが含まれていなければ、hv_deleteは 削除された値の揮発性のコピー(mortal copy)を生成し、それを返しま す。
And more miscellaneous functions:
void hv_clear(HV*);
void hv_undef(HV*);
引数にAVを取る似たような関数と同様、hv_clearはハッシュテーブ ルにあるすべてのエントリーを削除しますがハッシュテーブル自身は削 除しません。hv_undefはエントリーとハッシュテーブル自身の両方 を削除します。
Perlは実際のデータをHEとtypedefされた構造体のリンクリストを使っ
て保持しています。これらは実際のキーと値のポインター(それに加え
て管理のためのちょっとしたもの)を保持しています。キーは文字列へ
のポインターであり、値はSV*です。しかしながら、一度HE*を持 てば、実際のキーと値とを取得するためには以下に挙げるようなルーチ
ンを使います。
I32 hv_iterinit(HV*);
/* ハッシュテーブルをたどるための開始点を準備 */
HE* hv_iternext(HV*);
/* 次のエントリーを取得して、キーと値両方を持つ構造
体へのポインターを返す */
char* hv_iterkey(HE* entry, I32* retlen);
/* HE 構造体からキーを取得し、そのキー文字列の長さを
返す */
SV* hv_iterval(HV*, HE* entry);
/* HE 構造体の値に対する SV ポインターを返す */
SV* hv_iternextsv(HV*, char** key, I32* retlen);
/* この便利なルーチンは、hv_iternext、hv_iterkey、
hv_itervalを組み合わせたものです。引数keyとretlen
は、キーとその長さを表わす戻り値です。関数の戻り値
はSV* で返されます。*/
配列変数の名前がわかるのであれば、
HV* perl_get_hv("package::varname", FALSE);
を使えば、その変数のHV へのポインタが得られます。その変数が存在しな い場合にはNULL を返します。
ハッシュアルゴリズムは PERL_HASH(hash, key, klen)
というマクロで定義されています。
hash = 0;
while (klen--)
hash = (hash * 33) + *key++;
tieされたハッシュに対するハッシュアクセス関数の使い方に 関する詳細は、Understanding the Magic of Tied Hashes and Arrays を参照してください。
バージョン5.004から、以下の関数がサポートされました。
HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash);
HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash);
bool hv_exists_ent (HV* tb, SV* key, U32 hash);
SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
SV* hv_iterkeysv (HE* entry);
これらの関数が、ハッシュ構造を扱うエクステンションの記述を単純に するC<SV*>キーを引数にとることに注意してください。これらの関数は また、SV*キーを(先に挙げた関数群とは異なり)文字列化することな しにtie関数に渡すことを許しています。
これらの関数はまた、ハッシュエントリー全体(HE*)を返したり受け 付けて、より効率良く使用します(特定の文字列に対するハッシュ番号
は毎回計算しなおす必要はないからです)。詳しくは後にある
API LISTING を参照してください。
以下に挙げるマクロは、ハッシュエントリーの内容にアクセスするのに 常に使わなければならないものです。これらのマクロはその引数を二度 以上評価する可能性があるので、マクロに対する引数は単純な変数でな ければならないということに注意してください。これらのマクロに関す る詳細はこのドキュメントの後のほうにあるL<API LISTING> を参照し てください。
HePV(HE* he, STRLEN len)
HeVAL(HE* he)
HeHASH(HE* he)
HeSVKEY(HE* he)
HeSVKEY_force(HE* he)
HeSVKEY_set(HE* he, SV* sv)
低レベルマクロが二つ定義されていますが、これらはSV*ではないキ ーを扱うときにのみ使わなければならないものです。
HeKEY(HE* he)
HeKLEN(HE* he)
hv_store と hv_store_ent の両方ともが、valに格納されて いる参照カウントのインクリメントをしないということに注意してくだ
さい。それは呼び出し側の責任です。これらの関数がNULLを返した場合、
呼び出し側はメモリーリークを防ぐために、valの参照カウントのデ クリメントを行う必要が一般にはあるでしょう。
リファレンスは、(リファレンスを含む) 他のスカラー型を指す特別な スカラー型です。
リファレンスを生成するには、
SV* newRV_inc((SV*) thing);
SV* newRV_noinc((SV*) thing);
のいずれかの関数を使います。
thingには、SV*, AV*, HV*のいずれかを置くことができま す。これら二つの関数は、newRV_incがthingの参照カウントをイ ンクリメントするがnewRV_noincはインクリメントしないという点を 除き、同一です。歴史的な理由により、newRVはnewRV_incの同義 語となっています。
リファレンスができれば、以下のマクロを使ってリファレンスの参照外し (dereference)ができます。
SvRV(SV*)
というマクロが使うことができ、返された SV* を AV* か HV* に キャストして、適切なルーチンを呼ぶことになります。
SVがリファレンスであるかどうかを確認するために、 以下のマクロを使うことができます。
SvROK(SV*)
リファレンスが参照している型を見つけるために、以下のマクロを 使いその戻り値をチェックします。
SvTYPE(SvRV(SV*))
戻り値として返される型で有益なものは以下の通りです。
SVt_IV スカラー
SVt_NV スカラー
SVt_PV スカラー
SVt_RV スカラー
SVt_PVAV 配列
SVt_PVHV ハッシュ
SVt_PVCV Code
SVt_PVGV グロブ (possible a file handle)
SVt_PVMG Blessed or Magical Scalar
詳しくはヘッダーファイル sv.hを参照してください。
Blessされたリファレンスとクラスオブジェクト
リファレンスはオブジェクト指向プログラミングをサポートするために も使われます。オブジェクト指向用語では、オブジェクトとはパッケー ジ(もしくはクラス)にblessされた単純なリファレンスです。一度bless されれば、プログラマーはそのリファレンスをクラスにおける様々なメ ソッドにアクセスするために使うことができます。
以下の関数を使って、リファレンスをパッケージにblessすることがで きます。
SV* sv_bless(SV* sv, HV* stash);
引数C<sv>はリファレンスでなければなりません。引数 stashはリフ ァレンスが属するクラスを指定します。クラス名のstashへの変換につ
いての詳細はStashes and Globs を参照してください。
/* Still under construction */
まだ存在していなければ、rvをリファレンスにアップグレードします。
rvが指し示すための新たなSVを生成します。classnameがナルでなけ れば、SVは指定されたクラスにblessされ、SVが返されます。
SV* newSVrv(SV* rv, char* classname);
整数、もしくは倍精度実数をC<rv>が参照しているSVへコピーします。 SVはclassnameがナルでなければblessされます。
SV* sv_setref_iv(SV* rv, char* classname, IV iv);
SV* sv_setref_nv(SV* rv, char* classname, NV iv);
ポインター値(アドレスであって、文字列ではありません!)をrvが参 照しているSVへコピーします。SVはclassnameがナルでなければbless されます。
SV* sv_setref_pv(SV* rv, char* classname, PV iv);
文字列をC<rv>が参照しているSVへコピーします。lengthに0を設定する
と、Perlが文字列の長さを計算します。SVはclassnameがナルでなけ ればblessされます。
SV* sv_setref_pvn(SV* rv, char* classname, PV iv, STRLEN length);
SVが特定のクラスにblessされているかどうかを検査します。 これは継承の関係のチェックはしません。
int sv_isa(SV* sv, char* name);
SVがblessされたオブジェクトのリファレンスであるかどうかを検査します。
int sv_isobject(SV* sv);
SVが特定のクラスから派生したものがどうかを検査します。
SVはblessされたオブジェクトのリファレンスでも、
クラス名を保持している文字列であってもかまいません。 これはUNIVERSAL::isaの機能を実装している関数です。
bool sv_derived_from(SV* sv, char* name);
ある特定のクラスの派生オブジェクトを受け取ったかどうか検査する には、以下のように書く必要があります。
if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... }
undefという値を持つあなたのPerlスクリプトからアクセスできる新た なPerlの変数を生成するには、以下に示すルーチンを変数の型に応じて 使います。
SV* perl_get_sv("package::varname", TRUE);
AV* perl_get_av("package::varname", TRUE);
HV* perl_get_hv("package::varname", TRUE);
二番目のパラメータとしてTRUEを使っているということに注意してくだ さい。新しい変数はここでデータ型に対する適切なルーチンを使うこと で設定することができます。
TRUE引数とビット和を取って、幾つかの追加機能を有効とする
ような二つのマクロがあります。
GV_ADDMULTI 変数に多重定義 (multiply defined)であると印を付け、
警告 "Name <varname> used only once: possible typo" を防ぎます。
GV_ADDWARN 変数が、その関数の呼び出し以前に存在してなかった場合に
"Had to create <varname> unexpectedly" という警告を発します。
パッケージ名を指定しなかった場合、変数はカレントパッケージで 生成されます。
Perlは参照カウント駆動(reference count-driven)のガーベッジコレク ション機構を使用しています。SV、AV、そしてHV(以下xVと省略します) はその一生を参照カウント1から始めます。xVの参照カウントが0まで落 ちた場合、そのリファレンスは破棄されて、それが使っていたメモリは 再利用できるようにされます。
これは、Perlレベルにおいては、変数がundefされるとかリファレンス を保持している最後の変数が変更されたとか上書きされるということが ない限りは起こりません。しかし内部的には、参照カウントは以下に挙 げるマクロを使って操作することができます。
int SvREFCNT(SV* sv);
SV* SvREFCNT_inc(SV* sv);
void SvREFCNT_dec(SV* sv);
その引数の参照カウントを操作する別の関数が一つあります。newRV_inc という関数がそれです。これは指定された引数の参照を生成して、その 副作用として引数の参照カウントをインクリメントします。もしこの副 作用が邪魔であれば、newRV_noincを代わりに使ってください。
たとえば、XSUB関数からリファレンスを返したいと思ったとしましょう。 XSUBルーチンの中で、初期値として参照カウント1を持つSVを生成しま す。それから今作成したSVを引数にしてnewRV_incを呼びます。これ は新たなSVとしての参照を返しますが、newRV_incに引数として渡し たSVの参照カウントは2にインクリメントされます。ここでXSUBルーチ ンからそのリファレンスを戻り値として返し、SVのことは忘れましょう。 けれどもPerlは忘れてません! 戻り値で返されたリファレンスが破棄さ れたときにはいつも、元々のSVの参照カウントが1へと減じられ、そし て何事もおこりません。そのSVは、Perl自身が終了するまではそれにア クセスするなんの手段も持たずに中ぶらりんになります。
ここでの正しい手順は、newRV_incではなくnewRV_noincを使うと いうことです。これによって、最後のリファレンスが破棄されたときに SVのリファレンスカウントは0となってそのSVが破棄されて、メモリー リークを食い止めます。
xVsを破棄するのを助けるような便利な関数が幾つかあります。これら の関数は “揮発性”(mortality)のコンセプトを導入します。ある揮発 性のxVはその参照カウントをデクリメントするようにマークしますが、 実際には“ちょっと後”(a short time later)までデクリメントが行な われません。一般的には、“ちょっと後”とは、XSUB関数の呼び出しの ような Perlの一つの文です。揮発性のxVが持っている参照カウントの デクリメントを行うタイミングの決定は二つのマクロ、SAVETMPSと FREETMPSに依存しています。これら二つのマクロについての説明は perlcall と perlxs を参照してください。
“Mortalization”はそれから、SvREFCNT_decに決定権を委ねます。 しかし、ある変数を二度揮発的にした場合、その参照カウントは後で二 度デクリメントされます。
揮発性の変数を生成するに当たっては十分注意すべきです。もし、同じ 変数を複合コンテキストの中で揮発性にしたり、ある変数を複数回揮 発性にしてしまったりすればおかしな自体が起こるかもしれません。
揮発性の変数を生成するには、
SV* sv_newmortal()
SV* sv_2mortal(SV*)
SV* sv_mortalcopy(SV*)
という関数を使います。最初のものは揮発性の SV を生成し、ふたつめ は既にある SV を揮発性の SV に変換します(そして、このために SvREFCNT_decを呼び出しを遅らせます)。三つめは、既に存在する SV の揮発性のコピーを生成します。
揮発性のルーチンは、単に SV のためだけではありません。AV や HV も、sv_2mortal や sv_mortalcopy ルーチンに、アドレス を (SV* にキャストして) 渡すことで、揮発性にすることができま す。
スタッシュ(``stash'')とは、パッケージ内にあるすべての異なるオブジ ェクトが入っているハッシュテーブル (連想配列) のことです。ハッシ ュテーブルにあるそれぞれの key は、(同じ名前のすべての異なる型の オブジェクトで共有される) シンボル名で、ハッシュテーブルの個々の value は、(グローバル値のための) GV と呼ばれます。GV には、
スカラー値
配列値
ハッシュ値
I/O値
フォーマット
サブルーチン
を含む (これらに限りませんが)、その名前の様々なオブジェクト へのリファレンスが次々に入ることになります。
“main”パッケージにあるアイテムを保持する“PL_defstash”と呼ばれる スタッシュがあります。他のパッケージにあるアイテムを取得するため には、パッケージ名に“::”を付加します。“Foo”というパッケージ にあるアイテムは“Foo::”という“PL_defstash”の中にあります。パッ ケージ “Bar::Baz”にあるアイテムは“Bar::”のスタッシュの中の“ Baz::”のスタッシュの中にあります。
特定のパッケージの HV ポインタの入手には、
HV* gv_stashpv(char* name, I32 create)
HV* gv_stashsv(SV*, I32 create)
という関数を使います。最初の関数が、リテラル文字列をとり、二番目 が SV
に入れた文字列を使います。stashは単なるハッシュなので、HV*
を受け取るということを忘れないでください。createフラグがセッ トされている場合には新たなパッケージを生成します。
gv_stash*v が要求する name はシンボルテーブルを手に入れようと
するパッケージの名前です。デフォルトのパッケージは、main
というものです。多重にネストしたパッケージであれば、Perl での場合と同様に、:: で区切って gv_stash*v に名前を渡すのが 正しい方法です。
もしbless されたリファレンスである SV があれば、
HV* SvSTASH(SvRV(SV*));
を使ってもスタッシュポインタを探すことができ、パッケージ名 自身は、
char* HvNAME(HV* stash);
で得られます。
Perl スクリプトへ bless された値を返す必要があれば、
SV* sv_bless(SV*, HV* stash)
という関数が使えます。最初の引数 SV* はリファレンスで、二番目 の引数がスタッシュです。返された SV* は、他の SV と同様に使う ことができます。
リファレンスとblessについてのより詳しい情報はperlrefを参照し てください。
スカラー変数は通常、整数、倍精度、ポインタ、リファレンスのうちの いずれか 一つの型をとります。Perl は実際のデータに対して、蓄積さ れている型から要求されている型へ、自動的に変換を行ないます。
ある種のスカラー変数は、複数の型のスカラーデータを持つようになっ
ています。たとえば変数 $! は、errno の数値としての値と、
strerrorやC<sys_errlist[]> から得たのと同値な文字列を持っています。
SV に複数のデータ値を入れるようにするには、二つのことをしなくて
はなりません。スカラー型を別に追加するために sv_set*vルーチン を使用すること。それから、フラグを設定して Perlに複数のデータを
持っていることを知らせることです。フラグを設定するための 四つの マクロは:
SvIOK_on
SvNOK_on
SvPOK_on
SvROK_on
です。使用するマクロは、最初にどの sv_set*v ルーチンを呼ぶの かに関わってきます。これは、sv_set*v ルーチンはすべて特定のデ
ータ型のビットだけを設定して、他をクリアしてしまうからです。
たとえば、``dberror'' という新しい Perl 変数を作って、エラー値を数 値とメッセージ文字列で持つようにするには、以下のように書きます:
extern int dberror;
extern char *dberror_list;
SV* sv = perl_get_sv("dberror", TRUE);
sv_setiv(sv, (IV) dberror);
sv_setpv(sv, dberror_list[dberror]);
SvIOK_on(sv);
sv_setiv と sv_setpv の順序が逆であった場合、SvIOK_on マク ロの代わりに SvPOK_on マクロを呼ばなければなりません。
[This section still under construction. Ignore everything here. Post no bills. Everything not permitted is forbidden.]
すべてのSVはmagical、つまり、通常のSVが持っていないような特殊な
属性を持つようにすることができます。これらの属性はMAGICとして typedefされている struct magicのリンクリストにあるSV構造体に 格納されます。
struct magic {
MAGIC* mg_moremagic;
MGVTBL* mg_virtual;
U16 mg_private;
char mg_type;
U8 mg_flags;
SV* mg_obj;
char* mg_ptr;
I32 mg_len;
};
これは、パッチレベル0の時点でのものです。変更される可能性が あります。
sv_magic関数を使うために、PerlはSVにmagicを追加します。
void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen);
引数C<sv>は、新たにmagical featureを獲得するSVへのポインターです。
svがまだmagicalでなければ、PerlはsvにSVt_PVMGフラグをセ ットするためにSvUPGRADEを使います。Perlはそれから、magical features
のリンクリストの先頭にそれを追加します。以前に存在していた同じタ
イプのmagicは削除されます。これはオーバーライドすることができ、
複数の同じ型のmagicのインスタンスを一つのSVに結び付けることがで
きるということに注意してください。
引数 name と namlen はある文字列とmagicとを結び付けるため
に使われます。典型的には変数の名前です。namlenはmg_lenフィ ールドに格納され、nameがナルでなく、namlen>=0であればmalloc されたnameのコピーがmg_ptrフィールドに格納されます。
関数 sv_magicは howをあらかじめ定義されている ``Magic Virtual Table''
のどれをC<mg_virtual>フィールドに設定するかを決定するのに使いま す。
引数C<obj>はMAGIC構造体のmg_objフィールドに格納されます。 これがsv引数と同じでなかった場合、objの参照カウントはイン クリメントされます。同じであった場合、もしくは引数 howが“#” かナルポインターであった場合には、objは参照カウントのインクリ メントをさせることなく格納されます。
同様にHVにmagicを付加する関数があります。
void hv_magic(HV *hv, GV *gv, int how);
これは単純にsv_magicを呼び出し、引数C<gv>を強制的にSVにし ます。
SVからmagicを取り除くには、sv_unmagicという関数を呼び出します。
void sv_unmagic(SV *sv, int type);
引数C<type>は、SVがmagicalにされたときのhowの値と同じにな るようにすべきです。
MAGIC構造体のmg_virtualフィールドはMGVTBLへのポインター で、これは関数ポインターの構造体であり、また対応する変数に対して
適用される可能性のあるさまざまな操作を扱うための “Magic Virtual Table”
を意味しています。
MGVTBLは、以下に挙げる五種類のポインターを持っています。
int (*svt_get)(SV* sv, MAGIC* mg);
int (*svt_set)(SV* sv, MAGIC* mg);
U32 (*svt_len)(SV* sv, MAGIC* mg);
int (*svt_clear)(SV* sv, MAGIC* mg);
int (*svt_free)(SV* sv, MAGIC* mg);
このMGVTBLはperl.hの中でコンパイル時に設定され、現在19の型(オ
ーバーロード込みで21)があります。これらの異なった構造体は、関数
が呼び出されたときに依存して追加動作を行うような様々なルーチンへ
のポインターを保持しています。
関数ポインター その振る舞い
---------------- ------------
svt_get SVの値が取得された後に何かを行う。
svt_set SVに値を代入した後で何かを行う。
svt_len SVの長さを報告する。
svt_clear SVが表わしているものををクリアする。
svt_free SVに結び付けられてい領域を解放する。
たとえば、vtbl_sv ('¥0'のmg_typeに対応します)と呼ばれる MGVTBL構造体の内容は以下の様になっています。
{ magic_get, magic_set, magic_len, 0, 0 }
したがって、あるSVがmagicalであると決定されてその型が'¥0'であっ
たとき、操作が実行されたならば、magic_getが呼び出されます。 magical 型に対するルーチンはすべて、magic_で始まります。
現時点でのMagic Virtual Tables の種類は以下の通りです。
mg_type MGVTBL magicalの型
------- ------ ----------------------------
¥0 vtbl_sv 正規表現???
A vtbl_amagic 演算子オーバーロード
a vtbl_amagicelem 演算子オーバーロード
c 0 演算子オーバーローディングで使われる
B vtbl_bm Boyer-Moore???
E vtbl_env ハッシュ %ENV
e vtbl_envelem ハッシュ %ENV の要素
g vtbl_mglob Regexp /g flag???
I vtbl_isa @ISA 配列
i vtbl_isaelem @ISA 配列の要素
L 0 (but sets RMAGICAL) Perl モジュール/デバッガー???
l vtbl_dbline デバッガー?
o vtbl_collxfrm Locale transformation
P vtbl_pack tieされた配列もしくはハッシュ
p vtbl_packelem tieされた配列もしくはハッシュの要素
q vtbl_packelem tieされたスカラーもしくはハンドル
S vtbl_sig シグナルハッシュ
s vtbl_sigelem シグナルハッシュの要素
t vtbl_taint Taintedness
U vtbl_uvar ???
v vtbl_vec ベクター
x vtbl_substr 部分文字列???
y vtbl_itervar Shadow "foreach" iterator variable
* vtbl_glob GV???
# vtbl_arylen 配列の長さ
. vtbl_pos $. スカラー変数
‾ None Used by certain extensions
テーブル中で大文字小文字の両方が存在していた場合、大文字は複合型 (リストもしくはハッシュ)の種類を表わすのに使われ、小文字はその複 合型の要素を表わすのに使われます。
magic type '‾'はエクステンションから使われ、Perl自身からは使われ ないように特別に定義されています。エクステンションは ‾ magic を プライベート情報を変数(典型的なオブジェクト)に‘アタッチ’(attach) するために使うことができます。これは、通常のperlコードが(ハッシ ュオブジェクトの要素を使うのとは違って)そのプライベート情報を壊 す恐れがないのでとても便利です。
複数のエクステンションが ‾ magicを使う可能性があるのでエクステン ションがそれを扱うには気をつけることが重要であることに注意してく ださい。典型的には、これはオブジェクトをエクステンションが扱える ように同じクラスにblessするときにのみ使います。これはまた、プラ イベートなデータ領域の先頭においてそれをチェックするためにI32 ‘シグネチャー’(signature)を付加するのに適切なものです。
sv_set*() と sv_cat*()といった関数群は そのターゲットに対してmagicを'セットしない'ということにも
注意してください。magicをセットするには、ユーザーが
svSETMAGICマクロを呼び出した後でこれらの関数を呼び出すか、 あるいはsv_set*_mg()か
sv_cat*_mg() の何れかの関数を使わなければなりません。 同様にgenericなCコードは、それが
magicを扱っていないような関数から得られた
SVを使っているのであれば、magicを'get'するためにSvGETMAGICを 呼び出してやらなければなりません。これらの関数については
API LISTINGで後述します。例を挙げると、sv_cat*()関数群の 呼び出しは通常C<SvSETMAGIC()>が続いている必要がありますが、
SvGETMAGICが先行している必要はありません。なぜなら、
その実装においてmagicを'get'するようになっているからです。
magicを見つけだす
MAGIC* mg_find(SV*, int type); /* その型のmagicポインターを見つける */
このルーチンはSVに格納されている MAGIC構造体へのポインターを 返します。SVがmagical featureを持っていなければ、NULLが返され、 SVがSvt_PVMGの型でなければPerlはコアダンプするかもしれません。
int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen);
このルーチンはsvが持っているmagicの型を検査します。その mg_type
フィールドが大文字であれば、mg_objがnsvにコピーされますが、 mg_typeフィールドは小文字に変更されます。
Tieされたハッシュと配列のmagicを理解する
tieされたハッシュと配列はmagic type 'P'の magical beastです。
警告: リリース 5.004にあるように、配列やハッシュに対するアクセス 関数の正しい使い方は、幾つかの注意点を理解していることを要求して います。これら幾つかの注意点は実際にはAPIにおけるバグとしてみな されるものであって、将来のリリースにおいては修正されます。また、 注意点は [MAYCHANGE]というブラケットで囲まれています。このセクシ ョンにある情報をあなたが実際に使おうというのであれば、将来それら は警告なしに変わる可能性があることに注意してください。
perlのtie関数は、ある変数とGET、SET等といった様々なメソッドを実装している オブジェクトとを結び付けるものです。 XSUBからperlのtie関数と等価な働きをさせるには、 ちょっとしたオマジナイをしなければなりません。 以下の例が必要なステップです。まず最初にハッシュを作り、それから tieメソッドを実装するクラスにblessした二番目のハッシュを作ります。 最後に二つのハッシュをtieし、新たに生成したtieされたハッシュに対する リファレンスを返します。以下の例ではMyTieクラスの中でTIEHASHを呼 び出していないということに注意してください。 この件に関する詳細はCalling Perl Routines from within C Programs を参照してください。
SV*
mytie()
PREINIT:
HV *hash;
HV *stash;
SV *tie;
CODE:
hash = newHV();
tie = newRV_noinc((SV*)newHV());
stash = gv_stashpv("MyTie", TRUE);
sv_bless(tie, stash);
hv_magic(hash, tie, 'P');
RETVAL = newRV_noinc(hash);
OUTPUT:
RETVAL
tieされた配列を引数に与えられたときの av_store関数は、単に配 列のmagicをC<mg_copy>を使って“stored”されるように値をコピーす るだけです。この関数は、その値が実際には配列に格納する必要のない ものであることを示すNULLを返す可能性があります。[MAYCHANGE] tie された配列に対して av_storeを呼び出した後、呼び出し側はTIEARRAY オブジェクトに対してPerlレベルの“STORE”メソッドを起動するため にav_storeを呼び出すことが通常は必要となります。av_storeが NULLを返したならば、メモリーリークを防ぐためにSvREFCNT_dec(val) を呼び出すことが必要となります。[/MAYCHANGE]
先のパラグラフの説明は、tieされたハッシュにアクセスするのに使用 するC<hv_store> と hv_store_ent についても同様です。
av_fetchと、対応するハッシュ関数C<hv_fetch>およびhv_fetch_ent はmg_copyを使って初期化が行なわれている未定義の揮発値を返しま す。返された値は、すでに揮発的であるかのように解放する必要のない ものです。[MAYCHANGE] しかし、TIEオブジェクトに対応したperlレベ ルの“FETCH”メソッドを実行するには、返されたその値に対して mg_get()を呼び出す必要があるでしょう。同様に、TIEオブジェクト に対する“STORE”メソッドの起動であるC<sv_setsv>を使って適切な値 を代入した後で、返された値に対してmg_set()を呼び出すことがで きます。[/MAYCHANGE]
[MAYCHANGE] 言い換えれば、配列やハッシュをフェッチしたりストアする関数は、 tieされている配列やハッシュに対する場合には実際に値をフェッチし たりストアしたりするわけではないということです。それらの関数は “ストア”されたり“フェッチ”された値に対してmagicを付加するた めに、単にmg_copyを呼び出すだけです。
現在(バージョン 5.004)、ハッシュや配列に対するアクセス関数の使用 する際には、ユーザーが“通常の”ハッシュや配列なのか、あるいはそ れがtieされたものであるのかを気をつけることが要求されています。 将来のバージョンでは、このAPIはtieされたデータに対するアクセスと 通常のデータに対するアクセスをより透過的にするために変更されるか もしれません。 [/MAYCHANGE]
TIEARRAYやTIEHASHといったインターフェースが、統一的なハッシュ/配 列構文を使うためのperlメソッドを起動をするための単なる“砂糖”で あることを良く理解したことでしょう。これらの“砂糖”の使用は幾ら かのオーバーヘッド(通常、FETCH/STORE操作当たり二つから四つの余分 なオペコード、それに加えてメソッドを起動するために必要なすべての 揮発性変数の生成)を招きます。このオーバーヘッドはTIEメソッド自身 がしっかりしたものであれば、ほぼ同等なくらい小さなものでしかあり ませんが、ほんの少し文が長いだけでもオーバーヘッドは無視できない ものになります。
変更を局所化する
Perlには非常に便利な構造があります。
{
local $var = 2;
...
}
この構造は以下のものとほぼ同じです
{
my $oldvar = $var;
$var = 2;
...
$var = $oldvar;
}
両者の最も大きな違いは、最初のものが
goto、return、die/evalなど どのようにブロックから脱出しようとも、
$varの元々の値を復帰するということです。
効率といった面では大きな違いはありません。
Perl APIを通してCから同様の処理を行う方法もあります。 擬似ブロック(pseudo-block)を生成し、そのブロックの最後で自動的に 復帰するような幾つかの変更を行います。ブロックから抜けるのは 陽に抜けるための指示があっても良いし、非局所的な脱出(die()を使ったもの) でもかまいません。ブロックに似たこの構造はENTER/LEAVEマクロ のペアによって生成されます(perlcallを 参照してください)。このような構造ではなにか重要な局所化された タスクのための特別なものを作成したり、あるいは 既に存在しているもの(Perlのサブルーチン/ブロックに束縛されたものとか、 あるいは解放する一時変数のペア)を使うことも可能です (二番目のケースでは、局所化するためのオーバーヘッドはほとんど 無視できるものです)。すべてのXSUBは自動的にENTER/LEAVEの ペアによって囲まれているということに注意してください。
このような擬似ブロックの中では以下のサービスが利用可能です:
これらのマクロはそれを囲むB<擬似ブロック>において 整数変数C<i>び値をリストアするようにします。
これらのマクロは、ポインターsもしくはpの値を リストアします。sはSV*に対する型変換をできるポインターで なければなりません。pはchar*への型変換が可能であるべきものです。
擬似ブロックの終端においてsvの参照カウントはデクリメントされます。 これはsv_2motralに似たものです。
OP *は擬似ブロックの終端においてop_free()されます。
pによって指し示されているメモリーの塊は擬似ブロックの終端で Safefreeされます。
擬似ブロックの終端において、
svに対応している カレントのスクラッチパッドにおけるスロットをクリアします。
擬似ブロックの終端でhvにあるキーkeyは削除されます。
keyによって指し示されている文字列はSafefree()されます。 short-lived
storageにあるI<key>を持っているものがあった場合には
以下のようにして対応する文字列が再割り当てされます。
SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf));
擬似ブロックの終端において関数C<f>が呼び出されます。この関数
fはvoid*であるC<p>のみを引数に取ります。
擬似ブロックの終端においてPerlの内部スタック(SP)のカレントオフセット がリストアされます。
以下のAPIリストは、変更可能なデータを指し示すポインター
(Cのポインターか、Perl的なGV *のいずれか) を必要とする関数群です。前述の
intを引数に取るマクロに似て、
int *を引数に取る関数があります。
Perlコード local $gvと等価です。
save_scalarに似ていますが、@gvと%gvの局所化を行います。
SVのカレントの値を複製し、カレントのENTER/LEAVE 擬似ブロック を抜けるときにSVの保存した値を復帰します。
複数の引数を長さmaxargのSV*の配列C<sarg>をとして取る
save_itemの複数の値を取るバリエーションです。
save_scalarに似ていますが、SV *の復帰を行います。
Aliasモジュールは呼び出し側のスコープ中での基本型の局所化を 実装します。スコープを持った何かの局所化に興味のある人は
そこに何があるかも見ておいた方が良いでしょう。
XSUBと引数スタック
XSUB の仕組みは、Perl プログラムが C のサブルーチンをアクセスす るための単純な方法です。XSUB には、Perl プログラムからの引数を入 れるスタックと、Perl のデータ構造を C の等価なものにマッピングす る方法を用意しています。
スタック引数はST(n) というマクロを使ってアクセスできます。こ れは、n 番目のスタック引数を返すものです。引数 0 は、Perl の
サブルーチン呼び出しで渡された最初の引数です。これらの引数は
SV* で、SV* が使われるところであればどこでも使うことができ ます。
ほとんどの場合には、C ルーチンからの出力は RETVAL ディレクティブ とOUTPUT ディレクティブを使って扱うことができます。しかし、引数 スタックのスペースがすべての返却値を扱うのに十分でなくなる場合が あります。例としては、引数をとらないでローカルなタイムゾーンと夏 時間の省略形の二つの返却値を返す、POSIXのtzname() の呼び出しがあ ります。
このような状況を扱うためには、PPCODE ディレクティブを使い、さらに
EXTEND(SP, num);
というマクロを使ってスタックを拡張します。ここで SP はス タックポインタで、num はスタックを拡張すべき要素の数です。
スタック上に場所を確保したら、IV、倍精度、文字列、SV ポ インタをプッシュする
PUSHi(IV)
PUSHn(double)
PUSHp(char*, I32)
PUSHs(SV*)
というマクロを使って、値をスタックへプッシュします。
これで、tzname をよぶ Perl プログラムでは、二つの値は、
($standard_abbrev, $summer_abbrev) = POSIX::tzname;
というように代入できます。スタックに値を積む、別の (おそら くはより簡単な) 方法は、
XPUSHi(IV)
XPUSHn(double)
XPUSHp(char*, I32)
XPUSHs(SV*)
というマクロを使うものです。こちらのマクロは、必要ならば自動的に スタックを調整してくれます。このため、EXTENDをスタックを拡張 するために呼ぶ必要はありません。
より詳しい情報は、perlxs と perlxstutを参照してください。
CプログラムからのPerlルーチンの呼び出し
C プログラムからPerl サブルーチンを呼び出すために使用することの できるルーチンが 四つあります。その四つは:
I32 perl_call_sv(SV*, I32);
I32 perl_call_pv(char*, I32);
I32 perl_call_method(char*, I32);
I32 perl_call_argv(char*, I32, register char**);
です。最もよく使われるはずのものは、perl_call_sv です。
引数 SV* には呼び出される Perl サブルーチンの名前か、そのサブ ルーチンへのリファレンスが含まれます。二番目の引数には、そのサブ ルーチンが呼び出されたコンテキストを制御するフラグが置かれます。 これは。サブルーチンに引数が渡されたか渡されていないか、エラーを どのようにトラップすべきなのか、どのように戻り値を返すのかを制御 するものです。
四つのルーチンはいずれも、サブルーチンが Perl スタック上に返した 引数の数を返します。
これらのルーチンを使うときには(perl_call_argvを除いて)、プロ グラマが Perl スタックを操作しなくてはなりません。以下のマクロと 関数が用意されています:
dSP
SP
PUSHMARK()
PUTBACK
SPAGAIN
ENTER
SAVETMPS
FREETMPS
LEAVE
XPUSH*()
POP*()
CからPerlを呼び出す約束ごとについての詳しい記述は perlcallを参照してください。
Perl API関数と共に使うような全てのメモリーはこのセクションで説明 されているマクロを使って扱うべきです。マクロは実際のmallocの 実装と、perlで使われているものとの差を透過的にします。
Perlと一緒に配布されていて、あなたがこれを使うことを推奨されてい るmallocの変種です。これは様々な大きさの未割り付けのメモリーをプ ールしておき、より早く割り付け要求に応えようとするものです。しか しながら一部のプラットフォームでは、これは不法なmallocエラーや freeエラーを引き起こす可能性があります。
New(x, pointer, number, type);
Newc(x, pointer, number, type, cast);
Newz(x, pointer, number, type);
これら三つのマクロはメモリーの割り付けのために使われます。
最初の引数C<x>は、メモリーに関する問題をデバッグするのを助けるた めに、誰がマクロを使ったのかを記録するのに使われていた“魔法のク ッキー”(magic cookie)でした。しかし、現在のコードでは、この機能 は使われていません(現在、ほとんどのPerl開発者は実行時メモリーチ ェッカーを使っています)。このため、この引数は任意の数値にするこ とができます。
二番目の引数C<pointer>は、新たにメモリーを割り付けられる変数の名 前にします。
三番目と四番目の引数 number and type は、指定された構造体 をどれだけ割り付けるのかを指定します。引数C<type>はsizeofに渡 されます。Newcに対する最後の引数 castは、引数C<pointer>が
引数C<type>と異なるときに使うべきものです。
NewやC<Newc>とは異なり、Newzは割り付けたメモリーのすべてを ゼロで埋めるためにmemzeroを呼び出します。
Renew(pointer, number, type);
Renewc(pointer, number, type, cast);
Safefree(pointer)
上記の三つのマクロは、メモリーのバッファーサイズを変更したりもう 使わなくなったメモリー領域を解放するために使われます。Renewと Renewcの引数は、“魔法のクッキー”引数が必要ないということを 除きそれぞれC<New>とRenewcに一致します。
Move(source, dest, number, type);
Copy(source, dest, number, type);
Zero(dest, number, type);
この三つのマクロは、それぞれ割り付けたメモリー領域に対する移動、
複写、ゼロで埋めるといったことに使われます。sourceとdest
という引数は、転送元と転送先の開始番地へのポインターです。Perlは、 構造体 typeの大きさ (sizeof関数を使います)のインスタンスの
number個分だけ、移動、複写、ゼロ埋めを行います。
最新リリースのPerlの開発では、Perlの“通常の”標準入出力ライブラ リに依存している部分を取り除くことと、Perlで別の標準入出力の実装 が使えるようにすることが試みられました。これにより必然的に、Perl と共にコンパイルされた標準入出力の実装を呼び出すような新しい abstraction layer が作られました。すべてのXSUBは、今では PerlIO abstraction layerの関数を使うべきで、これまで使っていた標準入出 力に関してのすべての仮定はすべきではありません。
PerlIO abstractionに関する詳しい記述は perlapioを参照してく ださい。
Cでの値をPerlスタックにプットする
たくさんのオペコード(これは内部的なperlスタックマシンでの基本的 な操作です)がSVをスタックに置きます。しかしながら、SVに対する最 適化のようなものは(通常は)毎回行なわれるわけではありません。オペ コードは解放されたり、生成されることのない特別に割り当てられたSV (targets)を再利用します。
それぞれのtargetsは、一度だけ生成して(ただし、後述するL<Scratchpads and recursion> を参照のこと)、オペコードがスタックに整数値、倍精 度実数値、文字列といったものを置くことを必要とするときに、スタッ クにtargetを置きます。
このtargetをスタックに置くためのマクロがPUSHTARGです。このマ クロは、他の多くのマクロが (X)PUSH[pni]を通じて間接的に使って
いるのと同様に、幾つかのオペコードで直接使われています。
スクラッチパッド
残っている疑問は、オペコードに対するI<target>s である SVをいつ生 成するのかということでしょう。その答えは、カレントユニット -- サ ブルーチンもしくは(サブルーチンの外側にある文のためのオペコード のための)ファイル -- がコンパイルされたときです。この間、特別な 無名配列が生成されます。これはカレントユニットのためのスクラッチ パッド (scrachpad)と呼ばれるものです。
スクラッチパッドはカレントユニットのための lexicalsやオペコード
のためのtargetであるSVを保持します。SVがあるスクラッチパッドを、
SVのフラグを見ることによって推測することができます。lexicalsでは
SVs_PADMYされていて、targetsではSVs_PADTMPがセットされ ています。
オペコードとtargetsの間の対応は一対一ではありません。あるユニ ットの翻訳木 (compile tree)にある異なるオペコードは、これが一時 変数の expected lifeと衝突していなければ同じtargetを使うことがで きます。
スクラッチパッドと再帰
コンパイルされたユニットがスクラッチパッド AVへのポインターを保 持しているということは、100%本当のことではありません。実際は、 (初期値では)一要素の AVへのポインターを保持していて、この要素が スクラッチパッド AVなのです。なぜ、こういう余計な間接レベルを必 要としているのでしょう?
その答えは再帰と、おそらく(もうすぐですが)スレッドです。こ れら二つは同じサブルーチンに対する別々の実行ポインターを生成しよ うとするかもしれません。子サブルーチンが(呼び出す子サブルーチン を覆っている寿命を持つ)親サブルーチンの一時変数を上書きしてしま わないように、親と子では、異なるスクラッチパッドを持つようにすべ きです(かつ、lexicalsは分けておくべきなのです!)。
各サブルーチンは、スクラッチパッドの(長さが1の)配列を伴って生成 されます。サブルーチンに対する各エントリーはその時点での再帰の深 さがこの配列の長さよりも大きくないことをチェックします。そして、 もしそうであれば、新たなスクラッチパッドが生成されて配列へとプッ シュされます。
このスクラッチパッドにある targetsは<undef>ですが、これらはす でに正しいフラグによってマークされています。
コンパイルされたコード
コード木
ここで、Perlによって変換されたプログラムの内部形式を説明しましょ う。簡単な例から始めます。
$a = $b + $c;
これは次のような木構造へ変換されます(実際にはもっと複雑です)。
assign-to
/ ¥
+ $a
/ ¥
$b $c
この木構造は、Perlがあなたのプログラムを解析したやり方を反映して いますが、実行の順序については反映していません。ノードの実行順序 を表わす木構造のノードを辿ろうとする別の“スレッド”(thread)があ ります。先の簡単な例では、次のようになります。
$b ---> $c ---> + ---> $a ---> assign-to
しかし、$a = $b + $cに対する実際の解析木はこれと異なります。 一部のノードが最適化されています。その結果として、実際の木構
造が私たちの単純な例よりも多くのノードを持っていたとしても、その
実行順序は同じになります。
木を検査する
perlをデバッグ用にコンパイルした(通常は Configureのコマンドラ インで -D optimize=-gを使って行います)場合、Perlのコマンドラ インで -Dxを指定することによって解析木を検査することができま
す。その出力はノード毎に数行を取り、$b+$cは以下のようになりま す。
5 TYPE = add ===> 6
TARG = 1
FLAGS = (SCALAR,KIDS)
{
TYPE = null ===> (4)
(was rv2sv)
FLAGS = (SCALAR,KIDS)
{
3 TYPE = gvsv ===> 4
FLAGS = (SCALAR)
GV = main::b
}
}
{
TYPE = null ===> (5)
(was rv2sv)
FLAGS = (SCALAR,KIDS)
{
4 TYPE = gvsv ===> 5
FLAGS = (SCALAR)
GV = main::c
}
}
この木には五つのノード(TYPE毎にひとつ)があって、そのうちの三
つだけが最適化されないものです(左側に数字のあるもの)。与えられた
ノードのすぐ下にある子供は同じレベルのインデントにあるC<{}>のペ
アに対応します。したがって、このリストは以下の木に対応します。
add
/ ¥
null null
| |
gvsv gvsv
実行順序は ===> マークによって表わされますから、3 4 5 6
(ノード 6は、上にあるリストには含まれません)となります。つまり、
gvsv gvsv add whatever ということになります。
この木構造は、yaccがperlプログラムを読み込んでその構造を解析して いる間に pseudo-compiler によって生成されます。yaccはボトムア ップで動作するので、perlによるコンパイルの最初のパスで行なわれま す。
perl開発者にとって興味深いのは、このパスで行なわれるいくつかの最
適化でしょう。これは、check routinesとも呼ばれる最適化です。 ノード名と対応するチェックルーチンとの間の対応はopcode.plに記 述されています(このファイルを修正した場合には、make regen_headers
を実行することを忘れないでください)。
チェックルーチンは、ノードが実行順序スレッドを除いて完全に構築さ れたときに呼び出されます。この時点では、構築されたノードに対する back-lineが存在しないので、トップレベルノードに対して、新たなノ ードを生成したりノードを解放したりすることを含めて、ほとんどの操 作を行うことができます。
このチェックルーチンは木に挿入すべきノードを返します(トップレベ ルのノードが変更されていなければ、チェックルーチンはその引数を返 します)。
規約により、チェックルーチンはck_*のような名前を持ちます。こ れらは通常サブルーチン new*OP (もしくはconvert)から呼び出 されます(これらのサブルーチンはperly.yから呼び出されます)。
コンパイルパス1a: 定数の畳み込み
チェックルーチンが呼び出された直後に、返されたノードはコンパイル 時実行のためのチェックが行なわれます。もしそうであれば(値が定数 であると判定された)、そのノードは即座に実行されて、“戻り値”に 対応する部分木は定数ノードで置換され、部分木が削除されます。
定数の畳み込み(constant folding)が働かなければ、実行順序スレッド が生成されます。
コンパイルパス2: コンテキスト伝播
解析木の一部分のコンテキストがわかっているとき、それは木の末端へ 伝播します。このとき、コンテキストは(実行時コンテキストの二種類 ではなく)void、 ブール、 スカラー、リスト、lvalueの五種類の値を 持つことができます。パス 1とは対照的に、このパスではトップから末 端へと処理が進みます。あるノードのコンテキストは、その下にある部 分のコンテキストを決定します。
コンテキストに依存した最適化はこのときに行なわれます。この動作で は解析木が(“スレッド”ポインターを通じて)後方参照を含んでいるの で、ノードをこの時にfree()することはできません。このステージでノ ードを最適化するのを許すために、対象となるノードはfree()されるか わりにnull()されます(つまり、そのノードの型がOP_NULLに変えられる ということ)。
コンパイルパス3: 覗き穴最適化
サブルーチン(もしくはevalかファイル)に対する解析木が生成され
た後で、そのコードに対する追加パスが実行されます。このパスはトッ
プダウンでもボトムアップでもなく、(条件に対するcompillcationを伴
った)実行順序です。これらの最適化はサブルーチンpeep()で行なわれ
ます。このステージで行なわれる最適化はパス2でのものと同じ制限に 従います。
APIリスト
エクステンションを書く人に便利であったり、他のエクステンションを 読んでいるときに見掛けるかもしれないような関数、マクロ、フラグ、 変数のリストを以下に挙げます
全てのPerl APIグローバル変数はPL_というプリフィックスをつけて参照
しなければならないということに注意してください。一部のマクロは
以前のものとの互換性を確保していてはいますが、それは将来のリリースに
おいては削除されるでしょう。
perlで始まっていない全てのPerl API関数を、 陽にPerl_プリフィックスを付けて参照することを強くおすすめします。
リストの順序は大小文字を無視して並べられていて、名前に含まれる '_'は順序づけにおいて無視されています。
配列をクリアし、空にします。配列自身が使っているメモリの解放はし ません。
void av_clear (AV* ar);
配列を pre-extendします。keyは、拡張された後の配列の添え字です。
void av_extend (AV* ar, I32 key);
配列中の指定された添え字にあるSVを返します。keyは添え字です。
lvalがセットされている場合、このフェッチはストアの一部となり ます。戻り値の SV*に対して参照外しをする場合にそれがナルでな いかをチェックしてください。
この関数をtieされた配列に対して使う場合の説明は Understanding the Magic of Tied Hashes and Arrays を参照してください。
SV** av_fetch (AV* ar, I32 key, I32 lval);
配列中で最大の添え字を返します。配列が空である場合には-1を返しま す。
I32 av_len (AV* ar);
新しいAVを生成して、SVのリストで埋めます。そのSVは配列へとコピー されるので、av_makeを呼び出した後で解放することもできます。新た なAVはその参照カウントとして1を持ちます。
AV* av_make (I32 size, SV** svp);
配列の最後にあるSVをポップします。配列が空である場合には&PL_sv_undef を返します。
SV* av_pop (AV* ar);
配列の末尾にSVをプッシュします。追加に対応するため、配列は自動的 に拡張されます。
void av_push (AV* ar, SV* val);
配列の先頭にあるSVをシフトして取り出します。
SV* av_shift (AV* ar);
SVを配列に格納します。配列の添え字はkeyで指定します。戻り値は 操作が失敗したり、(tieされている配列の場合のように)値を実際に配
列に格納する必要がないような場合にはNULLになります。そうでなけれ
ば、取得したオリジナルのSV*の参照外しをすることができます。呼 び出し側は、呼び出しを行う前にvalの参照カウントがインクリメン
トされる原因であり、関数がNULLを返したときには参照カウントのデク
リメントを行うということに注意してください。
この関数をtieされた配列に対して使う場合の説明は Understanding the Magic of Tied Hashes and Arrays を参照してください。
SV** av_store (AV* ar, I32 key, SV* val);
配列をundefineします。配列自身が使っていたメモリーを解放します。
void av_undef (AV* ar);
配列の先頭に、与えられた数だけのundef値をunsfhitします。追加
されたものにあわせて、配列は自動的に大きくなります。追加された新
しい要素に対して値を代入するには、この後でav_store を使わなけ ればなりません。
void av_unshift (AV* ar, I32 num);
xsubppによってセットアップされる、C++のXSコンストラクターに対
するクラス名を表わす変数です。これは常にchar*です。THISと
perlxsを参照してください。
Cのmemcpy関数に対する XSUB-writerのインターフェースです。s
は転送元、dは転送先、nは転送するアイテムの数、tは転送す るアイテムの型です。領域がオーバーラップしているコピーの場合は失
敗します。Moveを参照してください。
void Copy( s, d, n, t );
Perlのdie関数に対する XSUB-writerのインターフェースです。この 関数は、Cのprintf関数と同じような使い方で使用します。warn
を参照してください。
CVのスタッシュを返します。
HV* CvSTASH( SV* sv )
Perlが -dスイッチによってデバッグモードで実行されている場合、 このSVはサブルーチンがシングルステップで実行されるかどうかを表わ すブール値です。シングルステップは各ステップ毎に自動的に有効にな ります。これはPerlの$DB::singleという変数に対応するCの変数です。 PL_DBsubを参照してください。
Perlが -dスイッチによってデバッグモードで実行されている場合、 このGVはデバッグ対象となっているサブルーチンの名前を収めているSV を保持しています。これは、Perlの$DB::subという変数に対応するCの 変数です。PL_DBsingleを参照してください。サブルーチン名は以下の ようにして得ることができます。
SvPV( GvSV( DBsub ), len )
Perlが -dスイッチによってデバッグモードで実行されている場合に 使われるトレース変数です。これはPerlの$DB::trace変数に対応するC の変数です。PL_DBsingleを参照してください。
XSUBのためのオリジナルのスタックマークを保存します。 ORIGMARKを参照してください。
Perlの$^W変数に対応するCの変数です。
XSUBのためのスタックポインターのローカルなコピーを 宣言します。このコピーにはマクロC<SP>を使ってアクセス可能です。 SPを参照してください。
XSUBのために、スタックポインターとマークポインターをセットアップ
し、dSPとdMARKを呼び出します。これは通常、xsubppによって自動 的に行なわれます。スタックにあるアイテムの数を示すために変数
itemsを宣言します
エイリアスを持つXSUBのために変数 ixをセットアップします。これ は通常、xsubppによって自動的に行なわれます。
ファイルハンドルをbinmodeに切り替えます。iotypeはIoTYPE(io)を 含んでいるだろうものです。
do_binmode(fp, iotype, TRUE);
コールバックにあるブラケットを開きます。 LEAVE と perlcallを参照してください。
ENTER;
XSUBの戻り値のために引数スタックを拡張するのに使われます。
EXTEND( sp, int x )
Boyer-Mooreアルゴリズムを使ったfbm_instr()による高速検索ができるように するために文字列を解析します。
void fbm_compile(SV* sv, U32 flags)
strとstrendによって区切られる文字列中にあるSVの位置を返します。
文字列が見つからなかった場合にはNullchを返します。
svはfbm_compileされている必要はありませんが、その場合にはある場合に
比べると検索速度は遅くなります。
char* fbm_instr(char *str, char *strend, SV *sv, U32 flags)
コールバックにある一時変数のためのブラケットを閉じます。 SAVETMPS と perlcallを参照してください。
FREETMPS;
コールバックから返される引数が破棄されるべきものであることを示し ます。perlcallを参照してください。
コールバックをPerlのevalで囲むのを強制するために使われます。
perlcallを参照してください。
G_SCALAR か G_ARRAYしか返さないようなGIMME_Vの、バック ワードコンパチビリティのためのものです。voidコンテキストでは、こ れはG_SCALARを返します。
XSUB-writerのための、Perlのwantarrayに透過なものです。G_VOID、
G_SCALAR、G_ARRAY をそれぞれ、voidコンテキスト、スカラーコ
ンテキスト、配列コンテキストのときに返します。
コールバックに渡す引数がないことを示します。 perlcallを参照してください。
与えられたnameと、定義されたサブルーチンかNULLを使った globを返します。このglobは、与えられたstashか、 @ISAや@UNIVERSALを通じてアクセスできるスタッシュにあります。
引数 levelは0か-1であるべきです。level==0の場合、副作用と して(サブルーチンに対するエイリアスを含むことに成功した場合に)与
えられたstashにあるC<name>に対するglobを生成し、さらにこのglob
に対するキャッシュ情報のセットアップを行います。これは検索される
スタッシュすべてに同様です。
この関数はスタッシュ名のポストフィックスとして、 トークン "SUPER"を受付けます。
gv_fetchmethから返されたGVは、Perlプログラムからは参照するこ
とのできないような、メソッドキャッシュのエントリーである可能性が
あります。このため、perl_call_svを呼び出したとき、GVを直接使 うべきではありません。その代わりに、GVに対してGvCVマクロを使 って得ることのできる、メソッドのCVを使うべきなのです。
GV* gv_fetchmeth (HV* stash, char* name, STRLEN len, I32 level);
stashにあるメソッドを起動するために呼び出すサブルーチンを含む
globを返します。事実、オートローディングの直前でこれは``AUTOLOAD''
に対するglobとなる可能性があります。その場合、$AUTOLOADに対応す
る変数が既にセットアップされています。
gv_fetchmethod_autoloadの第三引数は、与えられたメソッドが存在
していなかった場合にAUTLOADのルックアップをするかしないかを決定し
ます。ゼロでないときはAUTOLOADの検索を行い、ゼロのときには行いま せん。gv_fetchmethod の呼び出しはgv_fetchmethod_autoload
にゼロでないautoloadパラメーターを渡したときと等価です。
これらの関数は、トークンC<``SUPER''>をメソッド名のプリフィックスとして 許します。
返されたglobを長い間保存しておきたいのなら、``AUTOLOAD''の存在をチ ェックする必要があるということに注意してください。これは、後での 呼び出しが$AUTOALODの値が変化したことによって、異なるサブルーチ ンをロードしてしまうかもしれないからです。
これらの関数は、gv_fetchmethにlevel==0を渡したときと同じ副 作用を持っています。nameは、その内容に':'か'¥''が含まれ ている場合には書き込み可能であるべきです。gv_fetchmethから返 されたGVをC<perl_call_sv>に渡したことに対する警告は、これらの関
数についても同じく適用されます。
GV* gv_fetchmethod (HV* stash, char* name);
GV* gv_fetchmethod_autoload (HV* stash, char* name,
I32 autoload);
=item G_VOID
voidコンテキストを示すために使われます。GIMME_Vとperlcallを 参照してください。
指定されたパッケージに対するスタッシュへのポインターを返します。
createがセットされていれば、指定したパッケージがない場合には
そのパッケージが生成されます。createがセットされていない場合 に指定したパッケージがなければ、NULLが返されます。
HV* gv_stashpv (char* name, I32 create);
指定したパッケージに対するスタッシュへのポインターを返します。 gv_stashpvを参照してください。
HV* gv_stashsv (SV* sv, I32 create);
GVからSVを返します。
このフラグは、ハッシュエントリーのlength slotや magic structures で使われ、char*ポインターであることを期待されているC<SV*>ポイ
ンターを含む構造体を指定します(情報のみ -- 使われません)。
ハッシュエントリーに格納されている計算済みハッシュを返します。
U32 HeHASH(HE* he)
ハッシュエントリーのキー スロットにあるポインターを返します。こ
のポインターはchar*かSV*のいずれかで、これはHeKLEN()の 値に依存します。これは代入することができます。HePV() や
HeSVKEY() といったマクロはキーの値を検索するために、通常望ま しいものです。
char* HeKEY(HE* he)
これが負であり、かつHEf_SVKEYに等しければ、エントリーがSV* キーを保持していることを示します。そうでなければ、これはキーの実 際の長さを保持しています。これは代入することができます。マクロ HePV()はキーの長さを検出するのに、通常望ましいものです。
int HeKLEN(HE* he)
char *としてのハッシュエントリーのキースロットを返し、SV*
キーで必要となるような参照外しなどを行います。文字列の長さはlen
に置かれます(これはマクロなので、&lenを使ってはいけません)。
キーの長さがどうなのかを気にしないのであれば、グローバル変数C<PL_na> を使うことができますが、これはローカル変数を使うよりも
非効率的です。しかし忘れないで欲しいのは、そういったperl
におけるハッシュのキーは埋め込まれているナルキャラクターに対して
自由であり、そのためC<strlen()>などを使ってハッシュキーの長さを
調べるのは良い方法ではないということです。これは他の場所で説明し ている SvPV() マクロについても同様です。
char* HePV(HE* he, STRLEN len)
SV*としてのキー、もしくはハッシュエントリーに SV*キーがない場合にはNullsvを返します。
HeSVKEY(HE* he)
SV*としてのキーを返します。ハッシュエントリーにchar*キーし かない場合には、一時的な揮発性SV*が生成されて返されます。
HeSVKEY_force(HE* he)
与えられたSV*にキーをセットし、SV*キーの存在を表わす適切な フラグを注意深くセットします。そして、同じSV*を返します。
HeSVKEY_set(HE* he, SV* sv)
ハッシュエントリーに格納されている(型 SV* の)値スロットを返し ます。
HeVAL(HE* he)
ハッシュをクリアーし、空にします。
void hv_clear (HV* tb);
ハッシュにあるキー/値のペアを削除します。値 SVはハッシュから取り
除かれて、呼び出し元に返されます。klenはキーの長さです。flags
の値は通常はゼロとなります。これにG_DISCARDをセットした場合にはNULL
が返されます。
SV* hv_delete (HV* tb, char* key, U32 klen, I32 flags);
ハッシュにあるキー/値のペアを削除します。値 SVはハッシュから取り
除かれて、呼び出し元に返されます。klenはキーの長さです。flags
の値は通常はゼロとなります。これにG_DISCARDをセットした場合にはNULL
が返されます。hashはあらかじめ計算されたハッシュ値を置きますが、
計算結果を問い合わせるには0とします。
SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
指定されたハッシュキーが存在するかどうかを表わすブール値を返しま す。klenはキーの長さです。
bool hv_exists (HV* tb, char* key, U32 klen);
指定されたハッシュキーが存在するかどうかを表わすブール値を返しま す。hashはあらかじめ計算されたハッシュ値を置きますが、計算結
果を問い合わせるには0とします。
bool hv_exists_ent (HV* tb, SV* key, U32 hash);
指定されたキーに対応する、ハッシュ中のSVを返します。klenはキ ーの長さです。lvalがセットされている場合、フェッチがストアの 一部分となります。戻り値 SV*の参照外しをする前に、それがナルで ないことをチェックしてください。
この関数をどのようにtieされたハッシュに使うかの情報は Understanding the Magic of Tied Hashes and Arrays を参照してください。
SV** hv_fetch (HV* tb, char* key, U32 klen, I32 lval);
指定されたキーに対応する、ハッシュ中のハッシュエントリーを返しま す。hashは、keyに対する正当な計算済みハッシュ値でなければ
なりません。もしくは、この関数にハッシュ値を計算させたいのであれ
ばここに0を置きます。lvalがセットされていると、フェッチはスト アの一部分となります。tbがtieされているハッシュの場合の戻り値 は静的な位置 (static
location)へのポインターです。したがって、何
かを格納する必要があるのなら、その構造体のコピーを取るようにして ください。
この関数をどのようにtieされたハッシュに使うかの情報は Understanding the Magic of Tied Hashes and Arrays を参照してください。
HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash);
ハッシュテーブルをたどるための開始点を準備します。
I32 hv_iterinit (HV* tb);
ハッシュの中に存在しているキーの数を返します(HvKEYS(tb)と同じです)。 この戻り値は現状ではtie
magicなしのハッシュに対してのみ意味があります。
注意: 5.004_65より前のバージョンでは、hv_iterinitは 使用中のハッシュバケツの数を返すのに使われていました。
もしあなたがそのような値を必要としているのなら、HvFILL(tb)という マクロを使って得ることができます。
ハッシュイテレーターの現在位置からキーを返します。 hv_iterinitを参照してください。
char* hv_iterkey (HE* entry, I32* retlen);
ハッシュイテレーターの現在位置から、SV*としてキーを返します。 この戻り値は常にキーの揮発性コピーとなります。hv_iterinitを参 照してください。
SV* hv_iterkeysv (HE* entry);
ハッシュイテレーターからエントリーを返します。 hv_iterinitを参照してください。
HE* hv_iternext (HV* tb);
一つの操作で hv_iternext、hv_iterkey、hv_iterval を 呼び出します。
SV * hv_iternextsv (HV* hv, char** key, I32* retlen);
ハッシュイテレーターの現在位置から値を返します。 hv_iterkeyを参照してください。
SV* hv_iterval (HV* tb, HE* entry);
ハッシュにmagicを付加します。sv_magicを参照してください。
void hv_magic (HV* hv, GV* gv, int how);
スタッシュのパッケージ名を返します。 SvSTASH, CvSTASHを参照してください。
char* HvNAME (HV* stash)
ハッシュにSVを格納します。そのハッシュキーはkeyで指定され、
klenはキーの長さです。hashパラメーターは、あらかじめ計算し
たハッシュ値です。Perlにハッシュ値を計算させるにはこれを0にしま
す。戻り値は、操作が失敗したり(tieされているハッシュのように)ハ
ッシュに実際に値を格納する必要のない場合にはNULLになります。
この関数をtieされているハッシュに使うやりかたについての詳細は Understanding the Magic of Tied Hashes and Arrays を参照して ください。
SV** hv_store (HV* tb, char* key, U32 klen, SV* val, U32 hash);
valをハッシュに格納します。ハッシュキーはkeyで指定します。
hashパラメーターはあらかじめ計算したハッシュ値です。Perlにこ
れを計算させるにはこの値を0にします。戻り値は生成された新しいハ
ッシュエントリーです。操作が失敗したり、(tieされているハッシュの
ように)ハッシュに実際に値を格納する必要のない場合にはNULLになり
ます。そうでない場合には、戻り値の内容にHe???マクロを使ってア クセスすることが可能です。呼び出し側は、呼び出しの前にvalの参 照カウントを適切にインクリメントする責任があり、また、関数がNULL
を返した場合には参照カウントをデクリメントする責任があるというこ
とに注意してください。
この関数をtieされているハッシュに使うやりかたについての詳細は Understanding the Magic of Tied Hashes and Arrays を参照して ください。
HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash);
ハッシュをundefineします。
void hv_undef (HV* tb);
charがアスキーのアルファベットキャラクター、もしくは数字であ
るかどうかを表わすブール値を返します。
int isALNUM (char c)
charがアスキーのアルファベットキャラクターであるかどうかを表
わすブール値を返します。
int isALPHA (char c)
charがアスキーの数字であるかどうかを表わすブール値を返します。
int isDIGIT (char c)
charが小文字のキャラクターであるかどうかを表わすブール値を返 します。
int isLOWER (char c)
charが空白であるかどうかを表わすブール値を返します。
int isSPACE (char c)
charが大文字のキャラクターであるかどうかを表わすブール値を返 します。
int isUPPER (char c)
xsubppによりセットアップされ、スタックにあるアイテムの数を表 わす変数です。perlxsを参照 してください。
xsubppによりセットアップされ、それを起動するのに使われたXSUB
のエイリアスを表わす変数です。perlxsを参 照してください。
コールバック上のブラケットを閉じます。ENTER と perlcallを 参照してください。
LEAVE;
SVの内容が数値のようにみなせるか(あるいは数値であるか)を検査します。
int looks_like_number(SV*)
XSUBに対するスタックマーカーの変数です。dMARKを参照してくださ い。
SVが表わしている magicalをクリアーします。sv_magicを参照して ください。
int mg_clear (SV* sv);
あるSVから別のSVへmagicをコピーします。sv_magicを参照してくだ さい。
int mg_copy (SV *, SV *, char *, STRLEN);
typeにマッチするSVへのmagic ポインターを検索します。 sv_magicを参照してください。
MAGIC* mg_find (SV* sv, int type);
SVが使用しているすべてのmagic storageを解放します。sv_magicを 参照してください。
int mg_free (SV* sv);
SVから値を取得した後でmagicを行います。sv_magicを参照してくだ さい。
int mg_get (SV* sv);
SVの長さを報告します。sv_magicを参照してください。
U32 mg_len (SV* sv);
SVのmagical statusをオンにします。sv_magicを参照してください。
void mg_magical (SV* sv);
SVに値を代入した後でmagicを行います。sv_magicを参照してくださ い。
int mg_set (SV* sv);
modglobalは、汎用の、インタープリターグローバルのHVで、 インタープリター毎の情報を保持するような エクステンションによって使われるものです。 場合によっては、データの共有をおこなうために エクステンションのシンボルテーブルとして使うことも可能です。 エクステンションのパッケージ名を、エクステンション固有のデータの 名前のプリフィックスとして使うのは良い考えです。
Cのmemmove関数に対するXSUBライターのインターフェースです。s
は転送元で、dが転送先、nがアイテムの数、tがその型です。 オーバーラップした移動も可能です。Copyを参照してください。
void Move( s, d, n, t );
文字列の長さについて考慮しないような場合のSvPVと共に使われる ような変数です。通常はローカル変数を宣言してそれを使った方が効率が良いです。
Cの malloc関数に対するXSUBライターの、キャスト付きインターフェースです。
void* Newc( x, void *ptr, int size, type, cast )
Perlでの sub FOO () { 123 }と等価な定数サブルーチンを 生成します。 void newCONSTSUB(HV* stash,
char* name, SV* sv)
新たなHVを生成します。参照カウントは1に設定されます。
HV* newHV (void);
SVに対するRVラッパーを生成します。元のSVの参照カウントは インクリメントされます。
SV* newRV_inc (SV* ref);
歴史的理由により、“newRV”は“newRV_inc”の同義語となっています。
SVに対するRVラッパーを生成します。元のSVの参照カウントは インクリメントされません。
SV* newRV_noinc (SV* ref);
新たなSVを生成します。非ゼロのlenパラメーターは SVが持つべき割り当てずみ文字列空間の大きさを示します。
余分な空間にはNULが埋められ、予約されます
(SvPOKは文字列が割り当てられていたとしてもSVをセットしません)。
新しいSVの参照カウントは1にセットされます。idは0から1299の 間の整数です(メモリーリークを見つけるのに使われます)。
SV* NEWSV (int id, STRLEN len)
新たなSVを生成し、整数値をそこにコピーします。SVの参照カウントは 1にセットされます。
SV* newSViv (IV i);
新たなSVを生成し、倍精度実数値をそこにコピーします。 SVの参照カウントは1にセットされます。
SV* newSVnv (NV i);
新たなSVを生成し、文字列をそこにコピーします。SVの参照カウントは
1にセットされます。lenがゼロの場合、Perlが長さを計算します。
SV* newSVpv (char* s, STRLEN len);
新たなSVを生成し、sprintfのような文字列書式によって初期化します。
SV* newSVpvf(const char* pat, ...);
新たなSVを生成し、文字列をそこにコピーします。
SVの参照カウントは1に設定されます、lenがゼロであった場合には 長さゼロの文字列が生成されます。
SV* newSVpvn (char* s, STRLEN len)
SVを指し示す RVの rv に対する新たなSVを生成します。rvがRV でない場合には、それはRVに昇格します。classnameがナルでない場 合には、生成されたSVは指定されたパッケージにblessされます。参照
カウントが1に設定された SVが返されます。
SV* newSVrv (SV* rv, char* classname);
元のSVを正確に複製したSVを生成します。
SV* newSVsv (SV* old);
PerlサブルーチンのようにXSUBをフックするためにxsubpp
が使います。
PerlサブルーチンのようにXSUBをフックするためにxsubpp
が使います。 サブルーチンに対してPerlのプロトタイプを追加します。
XSUBライターのためのmalloc関数のインターフェースです。 割り付けられた領域はmemzeroによってゼロで埋められます。
void* Newz( x, void *ptr, int size, type ) +
AVのナルポインター。
キャラクターのナルポインター。
CVのナルポインター。
HVのナルポインター。
SVのナルポインター。
XSUBのためのオリジナルスタックマークです。 dORIGMARKを参照してください。
新たなPerlインタープリターを割り付けます。 perlembedを参照してください。
指定されたPerlサブルーチンに対するコールバックを呼び出します。 perlcallを参照してください。
I32 perl_call_argv (char* subname, I32 flags, char** argv);
指定されたPerlサブルーチンに対するコールバックを呼び出します。 blessされたオブジェクトがスタック上になければなりません。 perlcallを参照してください。
I32 perl_call_method (char* methname, I32 flags);
指定されたPerlサブルーチンに対するコールバックを呼び出します。 perlcallを参照してください。
I32 perl_call_pv (char* subname, I32 flags);
SVにある名前を持った Perlサブルーチンに対するコールバックを呼び出します。perlcall を参照してください。
I32 perl_call_sv (SV* sv, I32 flags);
新しいPerlインタープリターの初期化を行います。perlembedを参照 してください。
Perlインタープリターをシャットダウンします。perlembedを参照し てください。
Perlに対し、SVにある文字列をC<eval>するように指示します。
I32 perl_eval_sv (SV* sv, I32 flags);
Perlに対して、与えられた文字列をC<eval>してその結果をSV* に返す ように指示します。
SV* perl_eval_pv (char* p, I32 croak_on_error);
Perlインタープリターを解放します。perlembedを参照してください。
指定されたPerl配列のAVを返します。createがセットされていて、 指定された変数が存在していなければAVが生成されます。createが セットされておらず、かつ、指定された変数がなかった場合にはNULLが
返されます。
AV* perl_get_av (char* name, I32 create);
指定されたPerlサブルーチンのCVを返します。createがセットされ ていて、指定された変数が存在していなければCVが生成されます。
createがセットされておらず、かつ、指定された変数がなかった場
合にはNULLが返されます。
CV* perl_get_cv (char* name, I32 create);
指定されたPerlハッシュのHVを返します。createがセットされてい て、指定された変数が存在していなければHVが生成されます。create
がセットされておらず、かつ、指定された変数がなかった場合にはNULL
が返されます。
HV* perl_get_hv (char* name, I32 create);
指定されたPerlスカラーのSVを返します。createがセットされてい て、指定された変数が存在していなければSVが生成されます。create
がセットされておらず、かつ、指定された変数がなかった場合にはNULL
が返されます。
SV* perl_get_sv (char* name, I32 create);
PerlインタープリターにPerlスクリプトを解析するよう指示します。 perlembedを参照してください。
PerlにモジュールをC<require>するよう指示します。
void perl_require_pv (char* pv);
Perlインタープリターに実行するよう指示します。perlembedを参照 してください。
スタックから整数をポップします。
int POPi();
スタックからlongをポップします。
long POPl();
スタックから文字列をポップします。
char* POPp();
スタックから倍精度実数をポップします。
double POPn();
スタックからSVをポップします。
SV* POPs();
コールバックにある引数のためのブラケットを開きます。PUTBACK と perlcallを参照してください。
PUSHMARK(p)
整数をスタックへプッシュします。スタックは、プッシュする要素を収 めるのに十分な大きさを持っていなければなりません。 'set' magicをハンドルします。 XPUSHiを参照してください。
void PUSHi(int d)
倍精度実数をスタックへプッシュします。スタックは、プッシュする要 素を収めるのに十分な大きさを持っていなければなりません。 'set' magicをハンドルします。 XPUSHnを参照してください。
PUSHn(double d)
文字列をスタックへとプッシュします。スタックは、プッシュする要素
を収めるのに十分な大きさを持っていなければなりません。
lenは文字列の長さを表わします。 'set' magicをハンドルします。
XPUSHpを参照してください。
void PUSHp(char *c, int len )
SVをスタックへプッシュします。スタックは、プッシュする要素を収め るのに十分な大きさを持っていなければなりません。 'set' magicをハンドルします。 XPUSHsを参照してください。
void PUSHs(sv)
スタックに符号なし整数をプッシュします。スタックにはこの要素を 収めるだけの空きがなければなりません。XPUSHuを参照してください。
void PUSHu(unsigned int d)
XSUB引数のためのブラケットを閉じます。これは通常、xsubppによ って扱われます。他の使い方については PUSHMARKと perlcall
を参照してください。
PUTBACK;
Cのrealloc関数に対する XSUB-writerのインターフェースです。
void* Renew( void *ptr, int size, type )
キャスト付きの、Cのrealloc関数に対する XSUB-writerのインター フェースです。
void* Renewc( void *ptr, int size, type, cast )
xsubppによってセットアップされ、XSUBの戻り値を保持する変数で
す。これは、常にXSUBにとって正しい型になります。
perlxsを参照してください。
Cのfree関数に対する XSUB-writerのインターフェースです。
Cのmalloc関数に対する XSUB-writerのインターフェースです。
Cのrealloc関数に対する XSUB-writerのインターフェースです。
文字列を安全な場所へとコピーします。これはSVを使いません。
char* savepv (char* sv);
文字列を安全な場所へコピーします。lenはコピーするバイト数を指 示します。これはSVを使いません。
char* savepvn (char* sv, I32 len);
コールバックにある一時変数のためにブラケットを開けます。FREETMPS と perlcallを参照してください。
SAVETMPS;
スタックポインターの再フェッチします。コールバックの後で使われます。
perlcallを参照してください。
SPAGAIN;
XSUBのスタック上にある要素にアクセスするために使われます。
SV* ST(int x)
二つの文字列が等しいかどうかを検査します。真か偽を返します。
int strEQ( char *s1, char *s2 )
二つの文字列を、s1がs2よりも大きい、もしくは両者が等しいか
どうかの検査をします。真か偽かの結果を返します。
int strGE( char *s1, char *s2 )
二つの文字列を、s1がs2よりも大きいかどうかの検査をします。 真か偽かの結果を返します。
int strGT( char *s1, char *s2 )
二つの文字列を、s1がs2よりも小さい、もしくは両者が等しいか
どうかの検査をします。真か偽かの結果を返します。
int strLE( char *s1, char *s2 )
二つの文字列を、s1がs2よりも小さいかどうかの検査をします。 真か偽かの結果を返します。
int strLT( char *s1, char *s2 )
二つの文字列が異なるかどうかを検査します。真か偽を返します。
int strNE( char *s1, char *s2 )
二つの文字列が等しいかどうかを検査します。パラメーターlenは、 比較を行うバイト数を指定します。真か偽を返します。
int strnEQ( char *s1, char *s2 )
二つの文字列が異なるものかどうかを検査します。パラメーターlen
は、比較を行うバイト数を指定します。真か偽を返します。
int strnNE( char *s1, char *s2, int len )
SVを揮発性にします。カレントのコンテキストが終了したとき、SVは破 棄されます。
SV* sv_2mortal (SV* sv);
SVを指定したパッケージにblessします。SVはRVでなければなりません。 パッケージは、そのスタッシュ(gv_stashpv()参照)によって指示さ れていなければなりません。SVの参照カウントは影響を受けません。
SV* sv_bless (SV* sv, HV* stash);
文字列を、SVにある文字列の終端に連結します。 'get' magicをハンドルしますが、'set' magicはハンドルしません。 sv_catpv_mgを参照してください。
void sv_catpv_mg (SV* sv, const char* ptr)
sv_catpvに似ていますが、'set' magicもハンドルします。
void sv_catpvn (SV* sv, char* ptr)
文字列を、SVにある文字列の終端に連結します。lenはコピーするバ イト数を指示します。 'get' magicをハンドルしますが、'set'
magicはハンドルしません。
sv_catpvn_mgを参照してください。
void sv_catpvn (SV* sv, char* ptr, STRLEN len);
sv_catpvnに似ていますが、'set' magicもハンドルします。
void sv_catpvn_mg (SV* sv, char* ptr, STRLEN len)
引数を sprintf のように処理し、SVにその結果を追加します。 'get' magicをハンドルしますが、'set'
magicはハンドルしません。 ほとんどの場合はこの関数を呼び出した後で'set'
magicをハンドルするために
SvSETMAGIC()が呼び出されます。
void sv_catpvf (SV* sv, const char* pat, ...);
sv_catpvfに似ていますが、'set' magicもハンドルします。
void sv_catpvf_mg (SV* sv, const char* pat, ...)
SV ssvにある文字列を、SV dsvにある文字列の終端へ連結します。 'get' magicをハンドルしますが、'set'
magicはハンドルしません。
sv_catsv_mgを参照してください。
void sv_catsv (SV* dsv, SV* ssv);
sv_catsvに似ていますが、'set' magicもハンドルします。
void sv_catsv_mg (SV* dsv, SV* ssv)
文字列バッファーの先頭からキャラクターを効率的に削除します。
SvPOK(sv)が真でなければならず、ptrは文字列バッファーの 内側のどこかを指し示すポインターでなければなりません。
ptrは調整後の文字列の先頭となります。
void sv_chop(SV* sv, char *ptr)
二つのSVにある文字列を比較します。sv1がsv2より小さいときに は -1を、両者が等しいときには0を、sv1がsv2より大きいときに は 1を返します。
I32 sv_cmp (SV* sv1, SV* sv2);
SVにある文字列の長さを返します。SvLENを参照してください。
int SvCUR (SV* sv)
SVにある文字列の長さを設定します。SvCURを参照してください。
void SvCUR_set (SV* sv, int val)
SVにある値の自動デクリメントを行います。
void sv_dec (SV* sv);
SVが指定したクラスから派生したものであるかどうかを示す
ブール値を返します。これはUNIVERSAL::isaを実装した関数です。 オブジェクトと同様、クラス名に対しても動作します。
bool sv_derived_from _((SV* sv, char* name));
SVにある文字列の終端のキャラクタへのポインターを返します。 SvCURを参照してください。キャラクターへは以下のようにして アクセスします。
char* SvEND(sv)
二つのSVにある文字列が同一のものであるかどうかをあらわすブール値 を返します。
I32 sv_eq (SV* sv1, SV* sv2);
SVが 'get' magic を有している場合にはmg_getを起動します。 このマクロはその引数を二回以上評価します。
void SvGETMAGIC(SV *sv)
指定されたバイト数だけの空間があるように SVにあるキャラクターバッファーを拡張します (予約分の空間はNULキャラクターで埋められることを思い出して ください)。必要であれば、拡張の ためにsv_growを呼び出します。キャラクターバッファーへのポイン ターを返します。
char* SvGROW(SV* sv, int len)
SVにあるキャラクターバッファーを拡張します。これは、sv_unref を使用して、SVをC<SVt_PV>へ昇格します。キャラクターバッファーへ のポインターを返します。SvGROWを使用します。
SVにある値の自動インクリメントを行います。
void sv_inc (SV* sv);
文字列を、SV中の指定されたオフセット/長さの位置に挿入します。 Perlのsubstr()関数と同様のものです。
void sv_insert(SV *sv, STRLEN offset, STRLEN len,
char *str, STRLEN strlen)
SVが整数を含んでいるかどうかを表わすブール値を返します。
int SvIOK (SV* SV)
SVのIVステータスをアンセットします。
void SvIOK_off (SV* sv)
SVに対し、そのSVが整数であるように指示します。
void SvIOK_on (SV* sv)
SVに対し、そのSVが整数であり、他のOKビットをすべてディセーブルに するように指示します。
void SvIOK_on (SV* sv)
SVが整数を含んでいるかどうかを表わすブール値を返します。SvIOK を使い、privateな設定を検査します。
int SvIOKp (SV* SV)
SVが指定したクラスにblessされているかどうかを表わすブール値を返 します。これは、subtypeをどのようにチェックするかを知らないので、 継承関係に確認するのにsv_derived_fromを使います。
int sv_isa (SV* sv, char* name);
SVが、blessされているオブジェクトを指すRVであるかどうかを表わす ブール値を返します。SVがRVでない場合、もしくはオブジェクトが blessされていない場合にはこれはfalseを返します。
int sv_isobject (SV* sv);
与えられたSVを強制的に整数に変換し、それを返します。
int SvIV (SV* sv)
SVに格納されている整数値を返します。SvIOKが真であると仮定します。
int SvIVX (SV* sv);
SVにある文字列バッファのサイズを返します。SvCURを参照してくだ さい。
int SvLEN (SV* sv)
SVにある文字列の長さを返します。SvCURを使ってください。
STRLEN sv_len (SV* sv);
SVにmagicを付加します。
void sv_magic (SV* sv, SV* obj, int how, char* name, I32 namlen);
元のSVのコピーである、新しいSVを生成します。生成されたSVは揮発性 である目印が付けられます。
SV* sv_mortalcopy (SV* oldsv);
揮発性である新たなSVを生成します。新たに作られたSVの参照カウント は1にセットされます。
SV* sv_newmortal (void);
SVが数値、つまり整数値か倍精度実数値を含んでいるかどうかを表わす ブール値を返します。
int SvNIOK (SV* SV)
SVのNT/IVステータスをアンセットします。
void SvNIOK_off (SV* sv)
SVが倍精度実数値を含んでいるかどうかを示すブール値を返します。 SvNIOKを使い、privateな設定を検査します。
int SvNIOKp (SV* SV)
SVが倍精度実数値を含んでいるかどうかを示すブール値を返します。
int SvNOK (SV* SV)
SVにあるNTステータスをアンセットします。
void SvNOK_off (SV* sv)
SVに対して、自分が倍精度実数であることを指示します。
void SvNOK_on (SV* sv)
SVに対して、自分が倍精度実数でありその他のOKフラグをディセーブル にするよう指示します。
void SvNOK_on (SV* sv)
SVが倍精度実数値を含んでいるかどうかを示すブール値を返します。 SvNOKを使い、privateな設定を検査します。
int SvNOKp (SV* SV)
SVを強制的に倍精度数値に変換し、それを返します。
double SvNV (SV* sv);
SVに格納されている倍精度数値を返します。
double SvNVX (SV* sv);
値がSVであるかどうかを示すブール値を返します。
int SvOK (SV* sv)
SvIVXがSvPVXに対する正しいオフセット値であるかどうかを示す ブール値を返します。このhackはSvPVの先頭からキャラクターを 取り除くスピードを向上するために内部的に使われます。 SvOOKが真であるとき、割り当てられた文字列バッファーの開始点は (SvPVX - SvIVX)となります。
int SvOOK(SV* sv)
SVがキャラクター文字列を保持しているかどうかの論理値を返します。
int SvPOK (SV* SV)
SVのPVステータスをアンセットします。
void SvPOK_off (SV* sv)
SVに対して、自分が文字列であることを指示します。
void SvPOK_on (SV* sv)
SVに対して、自分が文字列であるということを指示し、 他のOKビットをすべてディセーブルにするように指示します。
void SvPOK_on (SV* sv)
SVがキャラクター文字列を保持しているかどうかの論理値を返します。 private セッティングをチェックし、SvPOKを使います。
int SvPOKp (SV* SV)
SVにある文字列へのポインターか、SVが文字列を保持していない場合に はSVのstringfield formを返します。“get”magicをハンドルします。
char * SvPV (SV* sv, STRLEN len)
SvPVに似ていますが、SVを強制的に文字列(SvPOK)になります。 SvPVXを直接更新したい場合にはあなたは強制することを望むでしょう。
char* SvPV_force(SV* sv, STRLEN len)
SVにある文字列へのポインターを返します。SVは文字列を保持していな ければなりません。
char* SvPVX (SV* sv)
オブジェクトの参照カウントの値を返します。
int SvREFCNT (SV* sv);
SVで与えられたものの参照カウントを減じます。
void SvREFCNT_dec (SV* sv)
SVで与えられたものの参照カウントを増やします。
void SvREFCNT_inc (SV* sv)
SVがRVであるかを検査します。
int SvROK (SV* sv)
SVのRVステータスをリセットします。
void SvROK_off (SV* sv)
SVに、自分がRVであると指示します。
void SvROK_on (SV* sv)
SVを返すためにRVを参照はずしします。
SV* SvRV (SV* sv)
void SvSETMAGIC( SV *sv )
整数を与えられたSVへコピーします。'set' magicをハンドルしません。 sv_setiv_mgを参照してください。
void sv_setiv (SV* sv, IV num)
sv_setivに似ていますが、'set' magic をハンドルします。
void sv_setiv_mg (SV* sv, IV num)
倍精度浮動小数点数を与えられたSVへコピーします。 'set' magicをハンドルしません。 sv_setnv_mgを参照してください。
void sv_setnv (SV* sv, double num)
sv_setnvに似ていますが、'set' magicをハンドルします。
void sv_setnv_mg (SV* sv, double num)
文字列をSVへコピーします。文字列はnullで終端されていなければ なりません。これは'set' magicをハンドルしません。 sv_setpv_mgを参照してください。
void sv_setpv (SV* sv, const char* ptr);
sv_setpvに似ていますが、'set' magicをハンドルします。
void sv_setpv_mg (SV* sv, const char* ptr)
整数値を与えられたSVをコピーし、同様にその文字列値を更新します。 'set' magicをハンドルしません。sv_setpviv_mgを参照してください。
void sv_setpviv (SV* sv, IV num)
sv_setpvivに似ていますが、'set' magicをハンドルします。
void sv_setpviv_mg (SV* sv, IV num)
文字列をSVへコピーします。パラメーター lenはコピーされるバイ ト数を指示します。 'set' magicをハンドルしません。
sv_setpvn_mgを参照してください。
void sv_setpvn (SV* sv, const char* ptr, STRLEN len)
sv_setpvnに似ていますが、'set' magicをハンドルします。
void sv_setpvn_mg (SV* sv, const char* ptr, STRLEN len)
引数をC<sprintf>のように処理し、書式化された出力をSVにセットしま す。'set' magic をハンドルしません。 sv_setpvf_mgを参照してください。
void sv_setpvf (SV* sv, const char* pat, ...);
sv_setpvfに似ていますが、'set' magicをハンドルします。
void sv_setpvf_mg (SV* sv, const char* pat, ...)
整数値を、blessすることもできる新たなSVへコピーします。引数 rv
はRVへと昇格し、このRVは新たなSVを指し示すように変更されます。引 数C<classname>はblessするパッケージを指示するものです。blessをし
ないためには、classnameにNullchをセットします。新たなSVが 返され、その参照カウントは1となります。
SV* sv_setref_iv (SV *rv, char *classname, IV iv);
倍精度実数値を、blessすることもできる新たなSVへコピーします。引 数 rvはRVへと昇格し、新たなSVを指し示すように変更されます。引 数C<classname>はblessするパッケージを指示するものです。blessをし
ないためには、classnameにNullchをセットします。新たなSVが 返され、その参照カウントは1となります。
SV* sv_setref_nv (SV *rv, char *classname, double nv);
ポインターを、blessすることもできる新たなSVへコピーします。引数
rvはRVへと昇格し、新たなSVを指し示すように変更されます。 引数C<pv>がNULLであれば、PL_sv_undefが新たなSVに格納されます。 引数C<classname>はblessするパッケージを指示するものです。blessをしな
いためには、classnameにNullchをセットします。新たなSVが返 され、その参照カウントは1となります。
SV* sv_setref_pv (SV *rv, char *classname, void* pv);
HV, AV, SV, CVのようなPerlの integral typeを使わないようにしてく ださい。これは、そういったオブジェクトにポインターのコピー処理を 行うことでおかしくなってしまうからです。
sv_setref_pvn は、このポインターのコピーではなく文字列をコピ ーしているということに注意してください。
文字列を、blessすることもできる新たなSVへコピーします。文字列の 長さをC<n>で指定しなければなりません。引数 rvはRVへと昇格し、 新たなSVを指し示すように変更されます。引数C<classname>はblessす
るパッケージを指示するものです。blessをしないためには、classnameに
Nullchをセットします。新たなSVが返され、その参照カウントは1と なります。
SV* sv_setref_pvn (SV *rv, char *classname, char* pv, I32 n);
sv_setref_pv は、文字列をコピーするのではなくポインターをコピ ーするということに注意してください。
dsvがssvと等しくなかったときにsv_setsvを呼び出します。 引数は二回以上評価される可能性があります。
void SvSetSV (SV* dsv, SV* ssv)
dsvとssvが等しくなかったときに呼び出される、非破壊的バージョンの sv_setsvを呼び出します。引数は二回以上評価される可能性があります。
void SvSetSV_nosteal (SV* dsv, SV* ssv)
送り元のSV ssvの内容を、送り先のSV dsvにコピーします。 送り元のSVは、それが揮発性であった場合には破棄されるかもしれません。
'set' magicをハンドルしません。SVSetSV、SvSetSV_nosteal、
sv_setsv_mgといったマクロを参照してください。
void sv_setsv (SV* dsv, SV* ssv)
sv_setsvに似ていますが、'set' magicをハンドルします。
void sv_setsv_mg (SV* dsv, SV* ssv)
void sv_setuv (SV* sv, UV num)
sv_setuvに似ていますが、'set' magicをハンドルします。
void sv_setuv_mg (SV* sv, UV num)
SVのスタッシュを返します。
HV* SvSTASH (SV* sv)
汚染検査が有効なときにSVを汚染検査します。
void SvTAINT (SV* sv)
SVが汚染されているかどうかをチェックします。 汚染されていればTRUEを、そうでなければFALSEを返します。
int SvTAINTED (SV* sv)
SVを汚染除去します。Perlの基本的セキュリティ機構と同様 このルーチンを使うときは特に注意してください。 XSモジュールの作者は、汚染除去について良く理解しない限りは この関数を使うべきではありません。 perl標準のやり方では直接変数の汚染除去するのではなく、 注意深く構築された正規表現を使って汚染除去が 行われます。
void SvTAINTED_off (SV* sv)
Marks an SV as tainted.
void SvTAINTED_on (SV* sv)
スカラーに対する整数型。 svtypeを参照のこと。
スカラーに対するポインター型。 svtypeを参照のこと。
配列に対する型フラグ。 svtypeを参照のこと。
コードリファレンスのための型フラグ。 svtypeを参照のこと。
ハッシュに対する型フラグ。 svtypeを参照のこと。
blessされたスカラーに対する型フラグ。 svtypeを参照のこと。
スカラーに対する倍精度の型フラグ svtypeを参照のこと。
PerlがSVを真と評価するか偽と評価するか、defineされているかundefine なのかを表わすブール値を返します。'set' magicをハンドル しません。
int SvTRUE (SV* sv)
SVの型を返します。svtypeを参照してください。
svtype SvTYPE (SV* sv)
Perlの型のためのフラグの列挙で、sv.hというファイル中の svtype という列挙にあります。これらのフラグは、SvTYPEというマクロを 使って検査を行います。
SVのRVステータスをアンセットし、RVによって参照されているものの参 照カウントを減じます。これはnewSVrvの反転したものであると考え られます。SvROK_offを参照してください。
void sv_unref (SV* sv)
bool SvUPGRADE (SV* sv, svtype mt)
これはSVのundefです。これは常に &sv_undefとして参照されます。
SVに対して、ptrにある文字列を探し出すように指示します。通常は この文字列は
SVの内側に格納されますが、sv_usepvnは、SVが外側の文 字列 (outside
string)を使うことを許します。ptrはmallocによ って割り付けられたメモリーを指しているべきです。文字列の長さ、
lenは必ず指定しなければなりません。この関数はptrにより指さ れている領域をreallocするかもしれないので、ポインターはfreeされ
るべきではないし、プログラマーは、sv_usepvnに対して使った後でそ
のポインターを使うべきでもありません。'set' magicをハンドルしま せん。sv_usepvn_mgを参照してください。
void sv_usepvn (SV* sv, char* ptr, STRLEN len)
sv_usepvnに似ていますが、'set' magicをハンドルします。
void sv_usepvn_mg (SV* sv, char* ptr, STRLEN len)
vsprintfと同様にその引数を処理し、SVにフォーマット済み出力を
追加します。Cスタイルの変数引数リストがない(NULL)場合には
Svの配列を使用します。ロカール情報がフォーマットに使われた場合かどうかを
通知します。
void sv_catpvfn _((SV* sv, const char* pat, STRLEN patlen,
va_list *args, SV **svargs, I32 svmax,
bool *used_locale));
vatpvfnのように動作しますが、SVにテキストを追加するのではなく コピーします。
void sv_setpvfn _((SV* sv, const char* pat, STRLEN patlen,
va_list *args, SV **svargs, I32 svmax,
bool *used_locale));
SVを強制的に無符号整数に変換し、それを返します。
UV SvUV(SV* sv)
SVを強制的に無符号整数に変換し、それを返します。SvIOKが真であると仮定します。
UV SvUVX(SV* sv)
これはtrue SVです。PL_sv_noを参照してくさい。 これは常に&PL_sv_yesとして参照してください。
C++ のXSUBにおけるオブジェクトを指定する、xsubppによって設定 される変数です。CLASSおよび perlxsを参 照してください。
指定されたキャラクターを小文字に変換します。
int toLOWER (char c)
指定されたキャラクターを大文字に変換します。
int toUPPER (char c)
これはXSUBライターの、Perlのwarn関数に対するインターフェース です。この関数はCの関数 printf と同じように使います。croak()
を参照してください。
整数値をスタックにプッシュし、必要があればスタックの拡張を 行います。PUSHiを参照。 'set' magicをハンドルします。 します。 PUSHiを参照してください。
XPUSHi(int d)
倍精度数値をスタックにプッシュし、必要があればスタックの拡張を 行います。 'set' magicをハンドルします。 PUSHnを参照してください。
XPUSHn(double d)
文字列をスタックにプッシュし、必要があればスタックの拡張を 行います。lenはプッシュする文字列の長さを示します。 'set' magicをハンドルします。
PUSHpを参照してください。
XPUSHp(char *c, int len)
SVをスタックにプッシュし、必要があればスタックを拡張します。 'set' magicをハンドルします。 PUSHsを参照してください。
XPUSHs(sv)
スタックに符号なし整数をプッシュします。必要があればスタックを 拡張します。PUSHuを参照してください。
XSUBとそのCのパラメーターリストを宣言するためのマクロです。 これはxsubppによって扱われます。
XSUBから戻され、スタックにあるアイテムの数を示します。 これは通常C<xsubpp>によって扱われます。
XSRETURN(int x)
XSUBから即座に空リストを返します。
XSRETURN_EMPTY;
XSUBから即座に整数値を返します。XST_mIVを使います。
XSRETURN_IV(IV v)
XSUBから即座に &PL_sv_no を返します。 XST_mNOを使います。
XSRETURN_NO;
XSUBから即座に倍精度数値を返します。XST_mNVを使います。
XSRETURN_NV(NV v)
XSUBから即座に文字列のコピーを返します。XST_mPVを使います。
XSRETURN_PV(char *v)
XSUBから即座に &PL_sv_undef を返します。 XST_mUNDEFを使います。
XSRETURN_UNDEF;
XSUBから即座に &PL_sv_yes を返します。XST_mYESを使います。
XSRETURN_YES;
整数値をスタックのiで指定される場所に置きます。 その値は新しい揮発性SV (mortal
SV)に格納されます。
XST_mIV( int i, IV v )
倍精度数値をスタックのiで指定される場所に置きます。 その値は新しい揮発性SV (mortal
SV)に格納されます。
XST_mNV( int i, NV v )
&PL_sv_noをスタックのiで指定される場所に置きます。
XST_mNO( int i )
文字列のコピーをスタックのiで指定される場所に置きます。 その値は新しい揮発性SV (mortal
SV)に格納されます。
XST_mPV( int i, char *v )
&PL_sv_undefをスタックのiで指定される場所に置きます。
XST_mUNDEF( int i )
&PL_sv_yesをスタックのiで指定される場所に置きます。
XST_mYES( int i );
XSモジュールに対するバージョン識別子。これは通常、ExtUtils::MakeMaker
によって自動的に使われます。XS_VERSION_BOOTCHECKを参照してください。
PMモジュールのバージョン変数と、XSモジュールのXS_VERSION変数 とがマッチするかを検査するためのマクロです。これは、通常はxsubpp
によって自動的に扱われます。perlxs
を参照してください。
Cのmemzero関数に対する XSUB-writerのインターフェースです。d
は対象となる場所、nはアイテムの数、tはアイテムの型です。
void Zero( d, n, t );
Until May 1997, this document was maintained by Jeff Okamoto <okamoto@corp.hp.com> It is now maintained as part of Perl itself.
With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, Stephen McCamant, and Gurusamy Sarathy.
+API Listing originally by Dean Roehrich <roehrich@cray.com>