-*- buffer-read-only: t -*-

!!!!!!! DO NOT EDIT THIS FILE !!!!!!! This file is built by autodoc.pl extracting documentation from the C source files.

NAME

perlapi - perl public API の自動生成ドキュメント

DESCRIPTION

このファイルは embed.pl で生成された perl の公式な API のドキュメントです; 特にエクステンションの作者が使うかもしれない関数、マクロ、フラグ、変数の 一覧です。 ここに挙げられていないどの関数のインターフェースも予告なしに 変更されることがあります。 この理由により、エクステンションを書くときに proto.h に挙げられている関数を 盲目的に使うことは避けるべきです。

全ての Perl API グローバル変数は PL_ という接頭辞をつけて 参照しなければならないということに注意してください。 一部のマクロは以前のものとの互換性を確保していてはいますが、それは将来の リリースにおいては無効になるかもしれません。

リストは大文字小文字を無視したアルファベット順です。

値を「ちょうだい」

GIMME

G_SCALARG_ARRAY しか返さないような GIMME_V の、過去互換性の ためのものです; 無効コンテキストでは、これは G_SCALAR を返します。 廃止予定です。 代わりに GIMME_V を使ってください。

        U32     GIMME
GIMME_V

XSUB 作成者のための、Perl の wantarray に透過なものです。 G_VOIDG_SCALARG_ARRAY をそれぞれ、無効コンテキスト、スカラ コンテキスト、リストコンテキストのときに返します。

        U32     GIMME_V
G_ARRAY

リストコンテキストを示すために使われます。 GIMME_VGIMMEperlcall を参照してください。

G_DISCARD

コールバックから返される引数が破棄されるべきものであることを示します。 perlcall を参照してください。

G_EVAL

コールバックを Perl の eval で囲むのを強制するために使われます。 perlcall を参照してください。

G_NOARGS

コールバックに渡す引数がないことを示します。 perlcall を参照してください。

G_SCALAR

スカラコンテキストを示すのに使われます。 GIMME_V, GIMME, perlcall を参照してください。

G_VOID

無効コンテキストを示すために使われます。 GIMME_Vperlcall を参照してください。

配列操作関数

AvFILL

av_len() と同様です。 廃止予定なので、代わりに av_len() を使ってください。

        int     AvFILL(AV* av)
av_clear

配列をクリアし、空にします。 配列自身が使っているメモリの解放はしません。

        void    av_clear(AV* ar)
av_create_and_push

SV を配列の最後にプッシュします; もし必要なら配列を作ります。 一般的に複製された慣用句を削除するための小さい内部ヘルパーです。

注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。

        void    av_create_and_push(AV **const avp, SV *const val)
av_create_and_unshift_one

SV を配列の最初に unshift します; もし必要なら配列を作ります。 一般的に複製された慣用句を削除するための小さい内部ヘルパーです。

注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。

        SV**    av_create_and_unshift_one(AV **const avp, SV *const val)
av_delete

配列から、添え字が key の要素を削除します。 削除された要素を返します。 もし flagsG_DISCARD なら、要素は解放されて NULL が返されます。

        SV*     av_delete(AV* ar, I32 key, I32 flags)
av_exists

添え字が key の要素が既に初期化されているなら真を返します。

これは、初期化されていない配列要素は &PL_sv_undef が セットされているという事実に依存しています。

        bool    av_exists(AV* ar, I32 key)
av_extend

配列を事前拡張します。 key は、拡張された後の配列の添え字です。

        void    av_extend(AV* ar, I32 key)
av_fetch

配列中の指定された添え字にある SV を返します。 key は添え字です。 lval がセットされている場合、フェッチはストアの一部となります。 戻り値の SV* に対して参照外しをする場合にそれがヌルでないかを チェックしてください。

この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。

        SV**    av_fetch(AV* ar, I32 key, I32 lval)
av_fill

配列の最大の添え字を与えられた数値にセットします; Perl の $#array = $fill; と等価です。

av_fill() から返った後、配列の要素数は fill + 1 になります。 配列が以前より短くなった場合は、追加された要素は PL_sv_undef が セットされます。 配列がより長くなった場合は、超過した要素は解放されます。 av_fill(av, -1)av_clear(av) と同じです。

        void    av_fill(AV* ar, I32 fill)
av_len

配列中で最大の添え字を返します。 配列の要素数は av_len(av) + 1 です。 配列が空である場合には -1 を返します。

        I32     av_len(const AV* ar)
av_make

新しい AV を生成して、SV のリストで埋めます。 その SV は配列へとコピーされるので、av_make を呼び出した後で 解放することもできます。 新たな AV はその参照カウントとして 1 を持ちます。

        AV*     av_make(I32 size, SV** svp)
av_pop

配列の最後にある SV をポップします。 配列が空である場合には &PL_sv_undef を返します。

        SV*     av_pop(AV* ar)
av_push

配列の末尾に SV をプッシュします。 追加されたものにあわせて、配列は自動的に大きくなります。

        void    av_push(AV* ar, SV* val)
av_shift

配列の先頭にある SV をシフトして取り出します。

        SV*     av_shift(AV* ar)
av_store

SV を配列に格納します。 配列の添え字は key で指定します。 戻り値は操作が失敗したり、(tie されている配列の場合のように)値を実際に 配列に格納する必要がないような場合には NULL になります。 さもなければ、取得したオリジナルの SV* の参照外しをすることができます。 呼び出し側は、呼び出しの前に val の参照カウントを適切にインクリメントし、 関数が NULL を返した場合には参照カウントをデクリメントする責任が あるということに注意してください。

この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。

        SV**    av_store(AV* ar, I32 key, SV* val)
av_undef

配列を undefine します。 配列自身が使っていたメモリーを解放します。

        void    av_undef(AV* ar)
av_unshift

配列の先頭に、与えられた数だけの undef 値を unsfhit します。 追加されたものにあわせて、配列は自動的に大きくなります。 追加された新しい要素に対して値を代入するには、この後で av_store を 使わなければなりません。

        void    av_unshift(AV* ar, I32 num)
get_av

指定された Perl 配列の AV を返します。 create がセットされていて、指定された変数が存在していなければ、 新たに生成されます。 create がセットされておらず、かつ、指定された変数がなかった場合には NULL が返されます。

注意: この関数の perl_ の形は廃止予定です。

        AV*     get_av(const char* name, I32 create)
newAV

新たな AV を生成します。 参照カウントは 1 に設定されます。

        AV*     newAV()
sortsv

配列をソートします。 以下は例です:

    sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);

現在のところ、これは常にマージソートを使います。 さらに柔軟なルーチンのためには sortsv_flags を参照してください。

        void    sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
sortsv_flags

様々なオプション付きで配列をソートします。

        void    sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags)

コールバック関数

call_argv

指定された Perl サブルーチンに対するコールバックを呼び出します。 perlcall を参照してください。

注意: この関数の perl_ の形は廃止予定です。

        I32     call_argv(const char* sub_name, I32 flags, char** argv)
call_method

指定された Perl サブルーチンに対するコールバックを呼び出します。 bless されたオブジェクトがスタック上になければなりません。 perlcall を参照してください。

注意: この関数の perl_ の形は廃止予定です。

        I32     call_method(const char* methname, I32 flags)
call_pv

指定された Perl サブルーチンに対するコールバックを呼び出します。 perlcall を参照してください。

注意: この関数の perl_ の形は廃止予定です。

        I32     call_pv(const char* sub_name, I32 flags)
call_sv

SV にある名前を持った Perl サブルーチンに対するコールバックを呼び出します。 perlcall を参照してください。

注意: この関数の perl_ の形は廃止予定です。

        I32     call_sv(SV* sv, I32 flags)
ENTER

コールバックにあるブラケットを開きます。 LEAVEperlcall を参照してください。

                ENTER;
eval_pv

Perl に対して、与えられた文字列を eval してその結果をSV* に返すように 指示します。

注意: この関数の perl_ の形は廃止予定です。

        SV*     eval_pv(const char* p, I32 croak_on_error)
eval_sv

Perl に対し、SV にある文字列を eval するように指示します。

注意: この関数の perl_ の形は廃止予定です。

        I32     eval_sv(SV* sv, I32 flags)
FREETMPS

コールバックにある一時変数のためのブラケットを閉じます。 SAVETMPSperlcall を参照してください。

                FREETMPS;
LEAVE

コールバック上のブラケットを閉じます。 ENTERperlcall を参照してください。

                LEAVE;
SAVETMPS

コールバックにある一時変数のためにブラケットを開けます。 FREETMPSperlcall を参照してください。

                SAVETMPS;

文字クラス

isALNUM

char が ASCII 英数字(下線を含む)、もしくは数字であるかどうかを表わす 真偽値を返します。

        bool    isALNUM(char ch)
isALPHA

char が ASCII 英数字であるかどうかを表わす真偽値を返します。

        bool    isALPHA(char ch)
isDIGIT

char が ASCII 数字であるかどうかを表わす真偽値を返します。

        bool    isDIGIT(char ch)
isLOWER

char が小文字であるかどうかを表わす真偽値を返します。

        bool    isLOWER(char ch)
isSPACE

char が空白であるかどうかを表わす真偽値を返します。

        bool    isSPACE(char ch)
isUPPER

char が大文字であるかどうかを表わす真偽値を返します。

        bool    isUPPER(char ch)
toLOWER

指定された文字を小文字に変換します。

        char    toLOWER(char ch)
toUPPER

指定された文字を大文字に変換します。

        char    toUPPER(char ch)

インタプリタのクローン化

perl_clone

現在のものをクローン化することによって新しいインタプリタを作成し、 それを返します。

perl_clone は以下のフラグを引数として受け取ります:

CLONEf_COPY_STACKS - これは、つまり、スタックもコピーするために使います; これがない場合、データのみをクローンし、スタックはしません; これがある場合、スタックをコピーして、新しいインタプリタは以前のものと まったく同じ位置から実行する準備が出来ています。 疑似 fork コードは COPY_STACKS を使いますが、threads->create は使いません。

CLONEf_KEEP_PTR_TABLE perl_clone は、古い変数へのポインタをキーとして、新しい変数を値として ptr_table を保持します; これにより、何かがクローンされて、再び クローンされないけれども単に値を使って参照カウントを増やしているかを チェックできるようにします。 KEEP_PTR_TABLE がセットされていないと、perl_clone は ptr_table_free(PL_ptr_table); PL_ptr_table = NULL; を使って ptr_table を削除します; これを保持し続ける理由は、図示する perl が スキャンする外側の変数の一部を複製したい場合; このコードの例は threads.xs create にあります。

CLONEf_CLONE_HOST これは win32 のもので、unix では無視されます; perl に、自身を クローンするのに(c++ である)win32host コードを知らせます; これは、 二つのスレッドを同時に実行したいなら、win32 で必要です; 単に何かを別々の perl インタプリタで実行したいなら、これは捨てて元のものを返します; 何もする 必要はありません。

        PerlInterpreter*        perl_clone(PerlInterpreter* interp, UV flags)

CV 操作関数

CvSTASH

CV のスタッシュを返します。

        HV*     CvSTASH(CV* cv)
get_cv

name の長さを得るために strlen を使い、それから get_cvn_flags を 呼び出します。

注意: この関数の perl_ の形は廃止予定です。

        CV*     get_cv(const char* name, I32 flags)
get_cvn_flags

指定された Perl サブルーチンの CV を返します。 flagsgv_fetchpvn_flags に渡されます。 GV_ADD がセットされ、Perl サブルーチンが存在しない場合は、これが 宣言されます(これは sub name; と同じ効果です)。 GV_ADD がセットされず、Perl サブルーチンが存在しない場合は、NULL が 返されます。

注意: この関数の perl_ の形は廃止予定です。

        CV*     get_cvn_flags(const char* name, STRLEN len, I32 flags)

組み込み関数

cv_undef

CV の全ての有効な要素を片付けます。 これは明示的な undef &foo によってか、参照カウントが 0 になることによって 起こります。 前者の場合、CvOUTSIDE ポインタは維持するので、全ての無名の子は完全な レキシカルスコープチェーンに従ったままです。

        void    cv_undef(CV* cv)
load_module

name の文字列部で示された名前のモジュールを読み込みます。 ファイル名ではなく実際のモジュール名を指定することに注意してください; つまり、"Foo/Bar.pm" ではなく "Foo::Bar" です。 flags は PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, PERL_LOADMOD_IMPORT_OPS の いずれか(あるいはフラグなしなら 0)です。 ver が指定されると、use Foo::Bar VERSION と同様のバージョン意味論を 提供します。 オプションで引き続く SV* 引数は、use Foo::Bar VERSION LIST と同様に、 モジュールの import() メソッドへの引数を指定するために使われます。

        void    load_module(U32 flags, SV* name, SV* ver, ...)
nothreadhook

スレッドがないときの perl_destruct のためのスレッドフックを提供する スタブです。

        int     nothreadhook()
perl_alloc

新たなPerl インタプリタを割り付けます。 perlembed を参照してください。

        PerlInterpreter*        perl_alloc()
perl_construct

新しいPerl インタプリタの初期化を行います。 perlembed を参照してください。

        void    perl_construct(PerlInterpreter* interp)
perl_destruct

Perl インタプリタをシャットダウンします。 perlembed を参照してください。

        int     perl_destruct(PerlInterpreter* interp)
perl_free

Perl インタプリタを解放します。 perlembed を参照してください。

        void    perl_free(PerlInterpreter* interp)
perl_parse

Perl インタプリタに Perl スクリプトを解析するよう指示します。 perlembed を参照してください。

        int     perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
perl_run

Perl インタプリタに実行するよう指示します。 perlembed を参照してください。

        int     perl_run(PerlInterpreter* interp)
require_pv

文字列引数の名前のファイルを require するように Perl に伝えます。 Perl コード eval "require '$file'" に類似しています。 実際このように実装されています; 代わりに load_module を使うことを 考慮してください。

注意: この関数の perl_ の形は廃止予定です。

        void    require_pv(const char* pv)

ファイル dump.c の関数

pv_display
  char *pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len,
                   STRLEN pvlim, U32 flags)

以下と似ています:

  pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);

は、len > cur で pv[cur] が "\0" なら、文字列に追加の "\0" が 追加されることを想定します。

最終的な文字列は pvlim より最大 7 文字長くなる可能性があることに 注意してください。

        char*   pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)
pv_escape
               |const STRLEN count|const STRLEN max
               |STRLEN const *escaped, const U32 flags

多くても pv の最初の "count" 文字をエスケープして、エスケープされた文字列の サイズは "max" は "max" 文字を超えず、不完全なエスケープシーケンスが 含まれないような結果を dsv に入れます。

flags に PERL_PV_ESCAPE_QUOTE が含まれているなら、文字列中のダブルクォートも エスケープされます。

通常は SV はエスケープされた文字列が準備される前にクリアされますが、 PERL_PV_ESCAPE_NOCLEAR がセットされているとこれは起こりません。

PERL_PV_ESCAPE_UNI がセットされているなら入力文字列は Unicode として 扱われます。 PERL_PV_ESCAPE_UNI_DETECT がセットされているなら入力文字列は Unicode かどうか 決定するために is_utf8_string() を使ってスキャンされます。

PERL_PV_ESCAPE_ALL がセットされていると、全ての入力文字は \x01F1 形式の エスケープを使って出力され、さもなければ 255 を超える文字のみがこの形式で エスケープされ、その他の表示できない文字は 8 進数か \n のような一般的な エスケープパターンを使います。 PERL_PV_ESCAPE_NOBACKSLASH なら、255 以下の全ての文字は表示可能として 扱われてリテラルとして出力されます。

PERL_PV_ESCAPE_FIRSTCHAR がセットされると、max に関わらず文字列の最初の 文字だけがエスケープされます。 文字列が utf8 で文字の値が >255 なら、普通の 16 進シーケンスとして 返されます。 従って出力は単一の文字、8 進エスケープシーケンス、\n のような 特殊エスケープ、3 桁以上の 16 進数のいずれかです。

PERL_PV_ESCAPE_RE が設定されると、使われるエスケープ文字は '\\' ではなく '%' になります。 これは正規表現がとてもしばしばバックスラッシュ並びを含んでいて、一方 '%' は パターン中で特に一般的な文字というわけではないからです。

dsv によって保持されている、エスケープされたテキストへのポインタを返します。

注意: この関数の perl_ の形は廃止予定です。

        char*   pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
pv_pretty
           |const STRLEN count|const STRLEN max\
           |const char const *start_color| const char const *end_color\
           |const U32 flags

文字列を何か表現可能なものに変換します; pv_escape() によるエスケープを扱い、 クォートと省略に対応しています。

PERL_PV_PRETTY_QUOTE フラグがセットされると、文字列中のダブルクォートが エスケープされて、全体がダブルクォートで囲まれます。 さもなければ、PERL_PV_PRETTY_LTGT がセットされていれば結果は山かっこで 囲まれます。

PERL_PV_PRETTY_ELLIPSES がセットされて、文字列中の全ての文字が 出力されないときは、省略記号 ... が文字列に追加されます。 これはクォートされた「後」に起きることに注意してください。

start_color が非 NULL なら、(もしあれば) 開きクォートの後、エスケープされた テキストの前に挿入されます。 end_color が非 NULL なら、エスケープされたテキストの後、クォートや 省略記号の前に挿入されます。

dsv によって保持されている、飾り付けられたテキストへのポインタを返します。

注意: この関数の perl_ の形は廃止予定です。

        char*   pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)

ファイル mathoms.c の関数

gv_fetchmethod

gv_fetchmethod_autoload を参照してください。

        GV*     gv_fetchmethod(HV* stash, const char* name)
pack_cat

Perl 関数 pack() を実装しているエンジンです。 注意: 引数 next_in_list と flags は使われません。 この呼び出しは使うべきではなりません; 代わりに packlist を使ってください。

        void    pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
sv_2pvbyte_nolen

SV のバイトエンコードされた表現へのポインタを返します。 副作用として、SV が UTF-8 から降格するかもしれません。

通常は SvPVbyte_nolen マクロ経由でアクセスします。

        char*   sv_2pvbyte_nolen(SV* sv)
sv_2pvutf8_nolen

SV の UTF-8 エンコードされた表現へのポインタを返します。 副作用として、SV が UTF-8 へ昇格するかもしれません。

通常は SvPVutf8_nolen マクロ経由でアクセスします。

        char*   sv_2pvutf8_nolen(SV* sv)
sv_2pv_nolen

sv_2pv() と同様ですが、長さも返しません。 普通は代わりにマクロラッパー SvPV_nolen(sv) を使うべきです。

        char*   sv_2pv_nolen(SV* sv)
sv_catpvn_mg

sv_catpvn に似ていますが、'set' magic もハンドルします。

        void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
sv_catsv_mg

sv_catsv に似ていますが、'set' magic もハンドルします。

        void    sv_catsv_mg(SV *dstr, SV *sstr)
sv_force_normal

SV への様々な種類のごまかしを巻き戻します; PV が共有文字列なら、 プライベートなコピーを作ります; リファレンスなら、リファレンスを止めます; グロブなら、xpvmg に降格します。 sv_force_normal_flags も参照してください。

        void    sv_force_normal(SV *sv)
sv_iv

複雑なマクロ式を扱えないコンパイラのための、SvIVx マクロの プライベート実装です。 代わりに、常にマクロを使ってください。

        IV      sv_iv(SV* sv)
sv_nolocking

ロックモジュールがないときに SV を「ロックする」ダミールーチンです。 NULL 関数をテストして、あるレベルでの strict での潜在的な警告を 回避するために存在します。

sv_nosharing() で「置き換え」られました。

        void    sv_nolocking(SV *sv)
sv_nounlocking

ロックモジュールがないときに SV を「アンロックする」ダミールーチンです。 NULL 関数をテストして、あるレベルでの strict での潜在的な警告を 回避するために存在します。

sv_nosharing() で「置き換え」られました。

        void    sv_nounlocking(SV *sv)
sv_nv

複雑なマクロ式を扱えないコンパイラのための、SvNVx マクロの プライベート実装です。 代わりに、常にマクロを使ってください。

        NV      sv_nv(SV* sv)
sv_pv

代わりに SvPV_nolen マクロを使ってください。

        char*   sv_pv(SV *sv)
sv_pvbyte

代わりに SvPVbyte_nolen マクロを使ってください。

        char*   sv_pvbyte(SV *sv)
sv_pvbyten

複雑なマクロ式を扱えないコンパイラのための、SvPVbyte マクロの プライベート実装です。 代わりに、常にマクロを使ってください。

        char*   sv_pvbyten(SV *sv, STRLEN *len)
sv_pvn

複雑なマクロ式を扱えないコンパイラのための、SvPV マクロの プライベート実装です。 代わりに、常にマクロを使ってください。

        char*   sv_pvn(SV *sv, STRLEN *len)
sv_pvutf8

代わりに SvPVutf8_nolen マクロを使ってください。

        char*   sv_pvutf8(SV *sv)
sv_pvutf8n

複雑なマクロ式を扱えないコンパイラのための、SvPVutf8 マクロの プライベート実装です。 代わりに、常にマクロを使ってください。

        char*   sv_pvutf8n(SV *sv, STRLEN *len)
sv_taint

SV を汚染します。 代わりに SvTAINTED_on を使ってください。

        void    sv_taint(SV* sv)
sv_unref

SV の RV ステータスをアンセットし、RV によって参照されているものの 参照カウントを減じます。 これは newSVrv の反転したものであると考えられます。 これは、flag がゼロのときの sv_unref_flags です。 SvROK_off を参照してください。

        void    sv_unref(SV* sv)
sv_usepvn

自身の文字列値を得るのに ptr を使うように SV に指示します。 flags を 0 にして sv_usepvn_flags を呼び出すことで実装されているので、 'set' magic をハンドルしません。 sv_usepvn_mg を参照してください。

        void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
sv_usepvn_mg

sv_usepvn に似ていますが、'set' magic をハンドルします。

        void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
sv_uv

複雑なマクロ式を扱えないコンパイラのための、SvUVx マクロの プライベート実装です。 代わりに、常にマクロを使ってください。

        UV      sv_uv(SV* sv)
unpack_str

Perl 関数 unpack() を実装しているエンジンです。 注意: 引数 strbeg, new_s, ocnt は使われません。 この呼び出しは使うべきではなりません; 代わりに unpackstring を 使ってください。

        I32     unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)

ファイル pp_ctl.c の関数

find_runcv

現在実行しているサブルーチンや eval に対応する CV の場所を調べます。 db_seqp が非 null なら、DB パッケージの CV は飛ばして、 *db_seqp を、DB:: コードが入った時点での cop シーケンス番号にします。 (デバッガが、デバッガ自身のスコープではなく、ブレークポイントのスコープで eval できるようにします)。

        CV*     find_runcv(U32 *db_seqp)

ファイル pp_pack.c の関数

packlist

Perl 関数 pack() を実装しているエンジンです。

        void    packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
unpackstring

Perl 関数 unpack() を実装しているエンジンです。 unpackstring は展開されたリスト要素をスタックに設定して、要素数を 返します。 この関数を呼ぶ前には PUTBACK を、呼んだ後には SPAGAIN を 使ってください。

        I32     unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)

GV 関数

GvSV

GV から SV を返します。

        SV*     GvSV(GV* gv)
gv_const_sv

gv がサブルーチンエントリがインライン化可能な定数サブルーチンである 型グロブであるか、gv がそのような型グロブに昇格するリファレンスの プレースホルダの場合、そのサブルーチンから返される値を返します。 さもなければ NULL を返します。

        SV*     gv_const_sv(GV* gv)
gv_fetchmeth

与えられた name と、定義されたサブルーチンか NULL を使ったグロブを 返します。 このグロブは、与えられた stash か、@ISA や UNIVERSAL:: を通じて アクセスできるスタッシュにあります。

引数 level は 0 か -1 であるべきです。 level==0 の場合、副作用として(サブルーチンに対するエイリアスを 含むことに成功した場合に)与えられた stash にある name に対する glob を生成し、さらにこの glob に対するキャッシュ情報のセットアップを 行います。

この関数はスタッシュ名のポストフィックスとして、トークン "SUPER" を 受け付けます。 gv_fetchmeth から返された GV は、Perl プログラムからは参照することの できないような、メソッドキャッシュのエントリである可能性があります。 このため、perl_call_sv を呼び出したとき、GV を直接 使うべきではありません; その代わりに、GV に対して GvCV マクロを使って 得ることのできる、メソッドの CV を使うべきです。

        GV*     gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
gv_fetchmethod_autoload

stash にあるメソッドを起動するために呼び出すサブルーチンを含むグロブを 返します。 事実、オートローディングの直前でこれは "AUTOLOAD" に対するグロブとなる 可能性があります。 その場合、$AUTOLOAD に対応する変数が既にセットアップされています。

gv_fetchmethod_autoload の第三引数は、与えられたメソッドが 存在していなかった場合に AUTLOAD のルックアップをするかしないかを決定します; ゼロでないときは AUTOLOAD の検索を行い、ゼロのときには行いません。 gv_fetchmethod の呼び出しは gv_fetchmethod_autoload に ゼロでない autoload パラメーターを渡したときと等価です。

これらの関数は、トークン "SUPER" をメソッド名の接頭辞として許します。 返された glob を長い間保存しておきたいのなら、"AUTOLOAD" の存在を チェックする必要があるということに注意してください。 これは、後での呼び出しが $AUTOALOD の値が変化したことによって、異なる サブルーチンをロードしてしまうかもしれないからです。

これらの関数は、gv_fetchmethlevel==0 を渡したときと同じ副作用を 持っています。 name は、その内容に ':''\'' が含まれている場合には書き込み 可能であるべきです。 gv_fetchmeth から返された GV を call_sv に渡したことに対する警告は、 これらの関数についても同じく適用されます。

        GV*     gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
gv_fetchmeth_autoload

gv_fetchmeth() と同じですが、オートロードされたサブルーチンも探します。 サブルーチンのグロブを返します。

GV なしのオートロードされたサブルーチンのために、level < 0 でも GV を 作成します。 スタブのないオートロードされたサブルーチンのために、結果の GvCV() は ゼロかもしれません。

        GV*     gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
gv_stashpv

指定されたパッケージに対するスタッシュへのポインタを返します。 name の長さを決定するために strlen を使い、それから gv_stashpvn() を呼び出します。

        HV*     gv_stashpv(const char* name, I32 flags)
gv_stashpvn

指定されたパッケージに対するスタッシュへのポインタを返します。 namelen 引数は name の長さをバイトで示します。 flagsgv_fetchpvn_flags() に渡されるので、GV_ADD を設定すると パッケージが既に存在していない場合は作成されます。 パッケージが存在しておらず、 flags が 0 (またはパッケージを作成しない その他の値)の場合は NULL が返されます。

        HV*     gv_stashpvn(const char* name, U32 namelen, I32 flags)
gv_stashpvs

gv_stashpvn と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。

        HV*     gv_stashpvs(const char* name, I32 create)
gv_stashsv

指定されたパッケージに対するスタッシュへのポインタを返します。 gv_stashpvn を参照してください。

        HV*     gv_stashsv(SV* sv, I32 flags)

便利な値

Nullav

AVのヌルポインタ。

Nullch

文字のヌルポインタ。

Nullcv

CVのヌルポインタ。

Nullhv

HVのヌルポインタ。

Nullsv

SVのヌルポインタ。

ハッシュ操作関数

get_hv

指定された Perl ハッシュの HV を返します。 create がセットされていて、指定された変数が存在していなければ、新たに 生成されます。 create がセットされておらず、かつ、指定された変数がなかった場合には NULL が返されます。

注意: この関数の perl_ の形は廃止予定です。

        HV*     get_hv(const char* name, I32 create)
HEf_SVKEY

このフラグは、ハッシュエントリの length slot や magic structures で使われ、 char* ポインタであることを期待されている SV* ポインタを含む構造体を 指定します。 (情報のみ -- 使われません)。

HeHASH

ハッシュエントリに格納されている計算済みハッシュを返します。

        U32     HeHASH(HE* he)
HeKEY

ハッシュエントリのキー スロットにあるポインタを返します。 このポインタは char*SV* のいずれかで、これは HeKLEN() の 値に依存します。 これは代入することができます。 HePV()HeSVKEY() といったマクロはキーの値を検索するために、 通常望ましいものです。

        void*   HeKEY(HE* he)
HeKLEN

これが負であり、かつ HEf_SVKEY に等しければ、エントリが SV* キーを 保持していることを示します。 そうでなければ、これはキーの実際の長さを保持しています。 これは代入することができます。 マクロ HePV() はキーの長さを検出するのに、通常望ましいものです。

        STRLEN  HeKLEN(HE* he)
HePV

char * としてのハッシュエントリのキースロットを返し、SV* キーで 必要となるような参照外しなどを行います。 文字列の長さは len に置かれます(これはマクロなので、&len を 使ってはいけません)。 キーの長さがどうなのかを気にしないのであれば、グローバル変数 PL_na を 使うことができますが、これはローカル変数を使うよりも非効率的です。 しかし忘れないで欲しいのは、そういった perl におけるハッシュのキーは 埋め込まれているヌル文字に対して自由であり、そのため strlen() などを使って ハッシュキーの長さを調べるのは良い方法ではないということです。 これは他の場所で説明している SvPV() マクロについても同様です。

        char*   HePV(HE* he, STRLEN len)
HeSVKEY

SV* としてのキー、もしくはハッシュエントリに SV* キーがない場合には NULL を返します。

        SV*     HeSVKEY(HE* he)
HeSVKEY_force

SV* としてのキーを返します。 ハッシュエントリに char* キーしかない場合には、一時的な揮発性 SV* が 生成されて返されます。

        SV*     HeSVKEY_force(HE* he)
HeSVKEY_set

与えられた SV* にキーをセットし、SV* キーの存在を表わす適切な フラグを注意深くセットし、同じ SV* を返します。

        SV*     HeSVKEY_set(HE* he, SV* sv)
HeVAL

ハッシュエントリに格納されている(型 SV* の)値スロットを返します。

        SV*     HeVAL(HE* he)
HvNAME

スタッシュのパッケージ名を返します; stash がスタッシュでない場合は NULL を返します。 SvSTASH, CvSTASH を参照してください。

        char*   HvNAME(HV* stash)
hv_assert

ハッシュが内部的に一貫した状態であるかを調べます。

        void    hv_assert(HV* tb)
hv_clear

ハッシュをクリアし、空にします。

        void    hv_clear(HV* tb)
hv_clear_placeholders

ハッシュからのプレースホルダをクリアします。 制限ハッシュに読み込み専用とマークされたキーがあって、その後キーが 削除されると、キーは実際には削除されず、&PL_sv_placeholder の値を 代入することでマークされます。 これはハッシュの反復のようなその後の操作では無視されるようになりますが、 将来の時点でキーに再代入されることで値を持てるようになっています。 この関数はこのようなハッシュからのプレースホルダキーをクリアします。 この使用例は Hash::Util::lock_keys() を参照してください。

        void    hv_clear_placeholders(HV* hb)
hv_delete

ハッシュにあるキー/値のペアを削除します。 値 SV はハッシュから取り除かれて、呼び出し元に返されます。 klen はキーの長さです。 flags の値は通常はゼロとなります; これに G_DISCARD をセットした場合には NULL が返されます。

        SV*     hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
hv_delete_ent

ハッシュにあるキー/値のペアを削除します。 値 SV はハッシュから取り除かれて、呼び出し元に返されます。 flags の値は通常はゼロとなります; これに G_DISCARD をセットした場合には NULL が返されます。 hash はあらかじめ計算されたハッシュ値を置きますが、計算結果を 問い合わせるには 0 とします。

        SV*     hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
hv_exists

指定されたハッシュキーが存在するかどうかを表わす真偽値を返します。 klen はキーの長さです。

        bool    hv_exists(HV* tb, const char* key, I32 klen)
hv_exists_ent

指定されたハッシュキーが存在するかどうかを表わす真偽値を返します。 hash はあらかじめ計算されたハッシュ値を置きますが、計算結果を 問い合わせるには 0 とします。

        bool    hv_exists_ent(HV* tb, SV* key, U32 hash)
hv_fetch

指定されたキーに対応する、ハッシュ中の SV を返します。 klen はキーの長さです。 lval がセットされている場合、フェッチはストアの一部となります。 戻り値 SV* の参照外しをする前に、それがヌルでないことを チェックしてください。

この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。

        SV**    hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
hv_fetchs

hv_fetch と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。

        SV**    hv_fetchs(HV* tb, const char* key, I32 lval)
hv_fetch_ent

指定されたキーに対応する、ハッシュ中のハッシュエントリを返します。 hash は、key に対する正当な計算済みハッシュ値でなければなりません; もしくは、この関数にハッシュ値を計算させたいのであればここに 0 を置きます。 lval がセットされていると、フェッチはストアの一部分となります。 tb が tie されているハッシュの場合の戻り値は静的な位置 (static location)へのポインタです。 したがって、何かを格納する必要があるのなら、その構造体のコピーを 取るようにしてください。

この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。

        HE*     hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
hv_iterinit

ハッシュテーブルをたどるための開始点を準備します。 ハッシュの中に存在しているキーの数を返します(HvKEYS(tb) と同じです)。 この戻り値は現状では tie magic なしのハッシュに対してのみ意味があります。

注意: 5.004_65 より前のバージョンでは、hv_iterinit は使用中の ハッシュバケツの数を返すのに使われていました。 もしあなたがそのような値を必要としているのなら、HvFILL(tb) という マクロを使って得ることができます。

        I32     hv_iterinit(HV* tb)
hv_iterkey

ハッシュイテレーターの現在位置からキーを返します。 hv_iterinit を参照してください。

        char*   hv_iterkey(HE* entry, I32* retlen)
hv_iterkeysv

ハッシュイテレーターの現在位置から、SV* としてキーを返します。 この戻り値は常にキーの揮発性コピーとなります。 hv_iterinit を参照してください。

        SV*     hv_iterkeysv(HE* entry)
hv_iternext

ハッシュ反復子からエントリを返します。 hv_iterinit を参照してください。

反復子が位置を失ったり無効になったりすることなく、反復子が現在指している ハッシュエントリに対して hv_delete または hv_delete_ent を 呼び出すことができます。 この場合現在のエントリは、これへの最後の参照を保持している反復子の ハッシュから削除されることに注意してください。 反復子は次の hv_iternext の呼び出しでエントリが解放されるようにマークが 付けられるので、すぐに反復子を捨ててはいけません; さもなければエントリは リークします; リソースの割り当て解除を引き起こすには hv_iternext を 呼び出してください。

        HE*     hv_iternext(HV* tb)
hv_iternextsv

一つの操作で hv_iternexthv_iterkeyhv_iterval を 呼び出します。

        SV*     hv_iternextsv(HV* hv, char** key, I32* retlen)
hv_iternext_flags

ハッシュ反復子からエントリを返します。 hv_iterinithv_iternext を参照してください。 flags の値は普通はゼロです; HV_ITERNEXT_WANTPLACEHOLDERS が セットされていると、(制限ハッシュのための) プレースホルダキーは通常のキーに 追加して返されます。 デフォルトではプレースホルダは自動的に飛ばされます。 現在のところプレースホルダは &Perl_sv_placeholder の値として 実装されています。 プレースホルダと制限ハッシュの実装は変更されるかも知れず、現在の実装は 整理するための変更には抽象化が不十分であることに注意してください。

注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。

        HE*     hv_iternext_flags(HV* tb, I32 flags)
hv_iterval

ハッシュ反復子の現在位置から値を返します。 hv_iterkey を参照してください。

        SV*     hv_iterval(HV* tb, HE* entry)
hv_magic

ハッシュに magic を付加します。 sv_magic を参照してください。

        void    hv_magic(HV* hv, GV* gv, int how)
hv_scalar

ハッシュをスカラコンテキストで評価して、結果を返します。 ハッシュが tie された場合は magic を扱います。

        SV*     hv_scalar(HV* hv)
hv_store

ハッシュに SV を格納します。 そのハッシュキーは key で指定され、klen はキーの長さです。 hash パラメーターはあらかじめ計算したハッシュ値です; 0 にすると Perl がこれを計算します。 戻り値は、操作が失敗したり(tie されているハッシュのように)ハッシュに 実際に値を格納する必要のない場合には NULL になります。 さもなければ、取得したオリジナルの SV* の参照外しをすることができます。 呼び出し側は、呼び出しの前に val の参照カウントを適切にインクリメントし、 関数が NULL を返した場合には参照カウントをデクリメントする責任が あるということに注意してください。 事実上成功した hv_store は val へのリファレンスを取得します。 これは通常あなたの求めているものです; 新しく作られた SV は参照カウント 1 を 持つので、あなたのコードがすることが SV を作成してハッシュを 保管することだけなら、hv_store は新しい SV へのリファレンスだけを所有し、 あなたのコードは整理のためにさらなる何かをする必要はありません。 hv_store は hv_store_ent の呼び出しとして実装されておらず、キーのための 一時的な SV を作成しないので、キーデータがすでに SV 形式に なっているのでなければ、hv_store_ent よりも hv_store を使ってください。

この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。

        SV**    hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
hv_stores

hv_store と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取り、ハッシュパラメータを除外します。

        SV**    hv_stores(HV* tb, const char* key, NULLOK SV* val)
hv_store_ent

val をハッシュに格納します。 ハッシュキーは key で指定します。 hash パラメーターはあらかじめ計算したハッシュ値です; 0 にすると Perl がこれを計算します。 戻り値は生成された新しいハッシュエントリです。 操作が失敗したり、(tie されているハッシュのように)ハッシュに実際に値を 格納する必要のない場合には NULL になります。 そうでない場合には、戻り値の内容に He? マクロを使ってアクセスすることが 可能です。 呼び出し側は、呼び出しの前に val の参照カウントを適切にインクリメントし、 関数が NULL を返した場合には参照カウントをデクリメントする責任が あるということに注意してください。 事実上成功した hv_store_ent は val へのリファレンスを取得します。 これは通常あなたの求めているものです; 新しく作られた SV は参照カウント 1 を 持つので、あなたのコードがすることが SV を作成してハッシュを 保管することだけなら、hv_store は新しい SV へのリファレンスだけを所有し、 あなたのコードは整理のためにさらなる何かをする必要はありません。 hv_store_ent は key だけを読み込むことに注意してください; val と違って 所有権を取らないので、key の参照カウントを正しく保守するのは全て 呼び出し側に責任があります。 hv_store は hv_store_ent の呼び出しとして実装されておらず、キーのための 一時的な SV を作成しないので、キーデータがすでに SV 形式に なっているのでなければ、hv_store_ent よりも hv_store を使ってください。

この関数をどのように tie されたハッシュに使うかに関するさらなる情報は "Understanding the Magic of Tied Hashes and Arrays" in perlguts を 参照してください。

        HE*     hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
hv_undef

ハッシュを undefine します。

        void    hv_undef(HV* tb)
newHV

新たな HV を生成します。 参照カウントは 1 に設定されます。

        HV*     newHV()

マジカル関数

mg_clear

SV が表わしている magical をクリアします。 sv_magic を参照してください。

        int     mg_clear(SV* sv)
mg_copy

ある SV から別の SV へ magic をコピーします。 sv_magic を参照してください。

        int     mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
mg_find

type にマッチする SV への magic ポインタを検索します。 sv_magic を参照してください。

        MAGIC*  mg_find(const SV* sv, int type)
mg_free

SV が使用しているすべての magic storage を解放します。 sv_magic を参照してください。

        int     mg_free(SV* sv)
mg_get

SV から値を取得した後で magic を行います。 sv_magic を参照してください。

        int     mg_get(SV* sv)
mg_length

SV の長さを報告します。 sv_magic を参照してください。

        U32     mg_length(SV* sv)
mg_magical

SV の magical status をオンにします。 sv_magic を参照してください。

        void    mg_magical(SV* sv)
mg_set

SV に値を代入した後で magic を行います。 sv_magic を参照してください。

        int     mg_set(SV* sv)
SvGETMAGIC

SV が 'get' magic を有している場合には mg_get を起動します。 このマクロは二回以上引数を評価します。

        void    SvGETMAGIC(SV* sv)
SvLOCK

適切なモジュールが読み込まれていれば、sv を得るための相互排他ロックを 準備します。

        void    SvLOCK(SV* sv)
SvSETMAGIC

SV が 'set' magic を持っている場合に、その SV に対して mg_set を 起動します。 このマクロは二回以上引数を評価します。

        void    SvSETMAGIC(SV* sv)
SvSetMagicSV

SvSetSV と同様ですが、後で set magic が必要です。

        void    SvSetMagicSV(SV* dsb, SV* ssv)
SvSetMagicSV_nosteal

SvSetSV_nosteal と同様ですが、後で set magic が必要です。

        void    SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
SvSetSV

dsv が ssv と等しくなかったときに sv_setsv を呼び出します。 引数は二回以上評価される可能性があります。

        void    SvSetSV(SV* dsb, SV* ssv)
SvSetSV_nosteal

dsv と ssv が等しくなかったときに呼び出される、非破壊的バージョンの sv_setsv を呼び出します。 引数は二回以上評価される可能性があります。

        void    SvSetSV_nosteal(SV* dsv, SV* ssv)
SvSHARE

適切なモジュールが読み込まれていれば、sv をスレッド間で共有するための 準備をします。

        void    SvSHARE(SV* sv)
SvUNLOCK

適切なモジュールが読み込まれていれば、sv の相互排他ロックを解放します。

        void    SvUNLOCK(SV* sv)

メモリ管理

Copy

C の memcpy 関数に対する XSUB 作成者のためのインターフェースです。 src は転送元、dest は転送先、nitems はアイテムの数、type は アイテムの型です。 領域がオーバーラップしているコピーの場合は失敗します。 Move を参照してください。

        void    Copy(void* src, void* dest, int nitems, type)
CopyD

Copy と同様ですが、dest を返します。 末尾呼び出し最適化を行うコンパイラで便利です。

        void *  CopyD(void* src, void* dest, int nitems, type)
Move

C の memmove 関数に対する XSUB 作成者のためのインターフェースです。 src は転送元、dest は転送先、nitems はアイテムの数、type は アイテムの型です。 オーバーラップした移動も可能です。 Copy を参照してください。

        void    Move(void* src, void* dest, int nitems, type)
MoveD

Move と同様ですが、dest を返します。 末尾呼び出し最適化を行うコンパイラで便利です。

        void *  MoveD(void* src, void* dest, int nitems, type)
Newx

XSUB 作成者のための malloc 関数のインターフェースです。

5.9.3 から、Newx() とその同類は古い New() API を置き換え、呼び出し側が 自分自身を識別できるようにデバッグの助けをするための最初の引数 x が なくなりました。 この助けは新しいビルドオプション PERL_MEM_LOG ("PERL_MEM_LOG" in perlhack 参照) で置き換えられました。 古い API は、古い perl に対応している XS モジュールが使えるように まだ存在しています。

        void    Newx(void* ptr, int nitems, type)
Newxc

C の malloc 関数に対する XSUB 作成者のためのキャスト付き インターフェースです。 Newx も参照してください。

        void    Newxc(void* ptr, int nitems, type, cast)
Newxz

XSUB 作成者のための malloc 関数のインターフェースです。 割り付けられた領域は memzero によってゼロで埋められます。 Newx も参照してください。

        void    Newxz(void* ptr, int nitems, type)
Poison

解放されたメモリへのアクセスを捕捉するための PoisonWith(0xEF) です。

        void    Poison(void* dest, int nitems, type)
PoisonFree

解放されたメモリへのアクセスを捕捉するための PoisonWith(0xEF) です。

        void    PoisonFree(void* dest, int nitems, type)
PoisonNew

割り当てられたけれども未初期化のメモリへのアクセスを捕捉するための PoisonWith(0xAB)。

        void    PoisonNew(void* dest, int nitems, type)
PoisonWith

うまくいけば未初期化メモリへのアクセスを捕捉するためにメモリを (あるバイトが繰り返される)バイトパターンで埋めます。

        void    PoisonWith(void* dest, int nitems, type, U8 byte)
Renew

C の realloc 関数に対する XSUB 作成者のためのインターフェースです。

        void    Renew(void* ptr, int nitems, type)
Renewc

キャスト付きの、C の realloc 関数に対する XSUB 作成者のための インターフェースです。

        void    Renewc(void* ptr, int nitems, type, cast)
Safefree

C の free 関数に対する XSUB 作成者のためのインターフェースです。

        void    Safefree(void* ptr)
savepv

Perl 版の strdup()pv の複製である、新しく割り当てられた文字列へのポインタを返します。 文字列のサイズは strlen() によって決定されます。 新しい文字列のために割り当てられたメモリは Safefree() 関数で解放できます。

        char*   savepv(const char* pv)
savepvn

もしあれば strndup() が行うことの Perl 版。 pv から len バイトの複製に加えて末尾の NUL バイトからなる、新しく 割り当てられた文字列へのポインタを返します。 新しい文字列のために割り当てられたメモリは Safefree() 関数で解放できます。

        char*   savepvn(const char* pv, I32 len)
savepvs

savepvn と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。

        char*   savepvs(const char* s)
savesharedpv

スレッド間で共有しているメモリで複製された文字列を割り当てるバージョンの savepv()

        char*   savesharedpv(const char* pv)
savesharedpvn

スレッド間で共有したメモリに複製した文字列を割り当てるバージョンの savepvn() です。 (NULL ポインタを受け付けないという違いもあります)

        char*   savesharedpvn(const char *const pv, const STRLEN len)
savesvpv

SvPV() を使った SV で渡されたものから複製した文字列を取得するバージョンの savepv()/savepvn() です。

        char*   savesvpv(SV* sv)
StructCopy

これはある構造体をもう一つにコピーするためのアーキテクチャに依存しない マクロです。

        void    StructCopy(type src, type dest, type)
Zero

C の memzero 関数に対する XSUB 作成者のためのインターフェースです。 dest は対象となる場所、nitems はアイテムの数、type は アイテムの型です。

        void    Zero(void* dest, int nitems, type)
ZeroD

Zero と同様ですが、dest を返します。 末尾呼び出し最適化を行うコンパイラで便利です。

        void *  ZeroD(void* dest, int nitems, type)

その他の関数

fbm_compile

Boyer-Moore アルゴリズムを使った fbm_instr() による高速検索が できるようにするために文字列を解析します。

        void    fbm_compile(SV* sv, U32 flags)
fbm_instr

strstrend によって区切られる文字列中にある SV の位置を返します。 文字列が見つからなかった場合には NULL を返します。 sv は fbm_compile されている必要はありませんが、その場合にはある場合に 比べると検索速度は遅くなります。

        char*   fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
form

sprintf 形式のフォーマットパターンと形式的な (非 SV) 引数を取って、 フォーマットされた文字列を返します。

    (char *) Perl_form(pTHX_ const char* pat, ...)

は文字列 (char *) が必要なあらゆる場所で使えます:

    char * s = Perl_form("%d.%d",major,minor);

単一のプライベートなバッファを使うので、いくつかの文字列を フォーマットしたいなら、以前の文字列を明示的にコピーしなければなりません (そして使い終わったらコピーを解放しなければなりません)。

        char*   form(const char* pat, ...)
getcwd_sv

sv をカレントワーキングディレクトリで埋めます

        int     getcwd_sv(SV* sv)
my_snprintf

利用可能で標準に準拠していれば、C ライブラリの snprintf の機能です (実際には vsnprintf を使います)。 しかし、vsnprintf が利用不可能なら、残念ながらバッファをオーバーランする 可能性のある安全でない vsprintf を使います (オーバーランチェックは ありますが、遅すぎるかもしれません)。 代わりに sv_vcatpvf を使うか、vsnprintf を使うことを考慮してください。

        int     my_snprintf(char *buffer, const Size_t len, const char *format, ...)
my_sprintf

バッファに書き込んだ文字列の長さが確実に返されるように、もし必要なら ラップされた、C ライブラリの sprintf です。 稀な ANSI 以前のシステムのみがラッパー関数を必要とします - 通常はこれは直接 sprintf を呼び出します。

        int     my_sprintf(char *buffer, const char *pat, ...)
my_vsnprintf

利用可能で標準に準拠していれば、C ライブラリの snprintf です。 しかし、vsnprintf が利用不可能なら、残念ながらバッファをオーバーランする 可能性のある安全でない vsprintf を使います (オーバーランチェックは ありますが、遅すぎるかもしれません)。 代わりに sv_vcatpvf を使うか、vsnprintf を使うことを考慮してください。

        int     my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
new_version

SV で渡されたものを基として新しいバージョンオブジェクトを返します:

    SV *sv = new_version(SV *ver);

渡された ver SV は変更されません。 SV を昇格したいなら "upg_version" を参照してください。

        SV*     new_version(SV *ver)
scan_version

バージョン文字列をパースした後の次の文字へのポインタを返します; また、SV に 渡されたものを RV に昇格させます。

関数は以下のように、既に存在する SV と共に呼び出されなければなりません

    sv = newSV(0);
    s = scan_version(s, SV *sv, bool qv);

バージョンとして正しい特性を持つように文字列に前処理を行います。 下線が含まれている(これがαバージョンであることを示します)なら、 オブジェクトにマークを付けます。 真偽値 qv は、たとえそうではなくても、バージョンに複数の小数点が 含まれているかのように解釈するべきであることを示します。

        const char*     scan_version(const char *vstr, SV *sv, bool qv)
strEQ

二つの文字列が等しいかどうかを検査します。 真か偽を返します。

        bool    strEQ(char* s1, char* s2)
strGE

二つの文字列を、s1s2 よりも大きい、もしくは両者が等しいかどうかの 検査をします。 真か偽を返します。

        bool    strGE(char* s1, char* s2)
strGT

二つの文字列を、s1s2 よりも大きいかどうかの検査をします。 真か偽を返します。

        bool    strGT(char* s1, char* s2)
strLE

二つの文字列を、s1s2 よりも小さい、もしくは両者が等しいか どうかの検査をします。 真か偽を返します。

        bool    strLE(char* s1, char* s2)
strLT

二つの文字列を、s1s2 よりも小さいかどうかの検査をします。 真か偽を返します。

        bool    strLT(char* s1, char* s2)
strNE

二つの文字列が異なるかどうかを検査します。 真か偽を返します。

        bool    strNE(char* s1, char* s2)
strnEQ

二つの文字列が等しいかどうかを検査します。 パラメーター len は、比較を行うバイト数を指定します。 真か偽を返します。 (strncmp へのラッパーです)

        bool    strnEQ(char* s1, char* s2, STRLEN len)
strnNE

二つの文字列が異なるかどうかを検査します。 パラメーター len は、比較を行うバイト数を指定します。 真か偽を返します。 (strncmp へのラッパーです)

        bool    strnNE(char* s1, char* s2, STRLEN len)
sv_destroyable

共有モジュールがないときにオブジェクトを破壊可能であると報告するダミー ルーチンです。 これは SV 引数を無視して、真を返します。 NULL 関数をテストして、あるレベルでの strict での潜在的な警告を 回避するために存在します。

        bool    sv_destroyable(SV *sv)
sv_nosharing

共有モジュールがないときに SV を「共有する」ダミールーチンです。 あるいは「ロックします」。 あるいは「アンロックします」。 言い換えると、単一の SV 引数を無視します。 NULL 関数をテストして、あるレベルでの strict での潜在的な警告を 回避するために存在します。

        void    sv_nosharing(SV *sv)
upg_version

SV をバージョンオブジェクトにその場で昇格します。

    SV *sv = upg_version(SV *sv, bool qv);

昇格された SV へのポインタを返します。 この SV が「拡張」版として解釈されることを強制したいなら、真偽値 qv を セットします。

        SV*     upg_version(SV *ver, bool qv)
vcmp

バージョンオブジェクトを認識する cmp。 両方のオペランドは既にバージョンオブジェクトに 変換されていなければなりません。

        int     vcmp(SV *lvs, SV *rvs)
vnormal

バージョンオブジェクトを受け付けて正規化された文字列表現を返します。 以下のように呼び出します:

    sv = vnormal(rv);

注意: オブジェクトを直接と、RV に含まれている SV のどちらでも渡せます。

        SV*     vnormal(SV *vs)
vnumify

バージョンオブジェクトを受け付けて正規化された浮動小数点表現を返します。 以下のように呼び出します:

    sv = vnumify(rv);

注意: オブジェクトを直接と、RV に含まれている SV のどちらでも渡せます。

        SV*     vnumify(SV *vs)
vstringify

以前のバージョンの Perl との最大限の互換性を維持するために、この関数は 元のバージョンにドットが一つだけか複数あるかに依存して、浮動小数点表記か 複数ドット表記のどちらかを返します。

        SV*     vstringify(SV *vs)
vverify

SV が正当なバージョンオブジェクトを含んでいるかを検証します。

    bool vverify(SV *vobj);

これは生の最小限の構造体だけを確認することに注意してください (従って 追加のハッシュエントリを含んでいるかもしれない派生クラスによって 混乱しません):

        bool    vverify(SV *vs)

MRO 関数

mro_get_linear_isa

このスタッシュに対して MRO が有効かどうかに依存して、スタッシュに対する mro_get_linear_isa_c3mro_get_linear_isa_dfs のどちらかを 返します。 返り値は読み込み専用の AV* です。

半永久的にどこかにこれを保管する計画がある場合、返り値に対する SvREFCNT_inc() に対して責任があります。 (さもなければ、次回キャッシュが無効化されるときに削除されるかもしれません)。

        AV*     mro_get_linear_isa(HV* stash)
mro_method_changed_in

スタッシュの全ての子クラスのメソッドキャッシュを無効にして、これによる 変更が通知されます。

理想的には、mro.c の外側の perl ソースの PL_sub_generation++ の全ての 実体はこれへの呼び出しで置き換えられるべきです。

Perl はメソッドが再定義されるかもしれない一般的な方法のほとんどを自動的に 扱います。 しかしキャッシュコードが気付くことなくスタッシュのメソッドを変更する いくつかの方法があります; この場合後でこのメソッドを呼び出す必要があります:

1) XS コードからスタッシュ HV エントリを直接操作する。

2) 読み込み専用スカラ定数へのリファレンスを、(constant.pm がしているように) 定数サブルーチンを作成するためにスタッシュエントリに代入する。

同じメソッドはピュア perl から mro::method_changed_in(classname) 経由で 利用可能です。

        void    mro_method_changed_in(HV* stash)

多重呼び出し関数

dMULTICALL

多重呼び出しのための局所変数を宣言します。 "Lightweight Callbacks" in perlcall を参照してください。

                dMULTICALL;
MULTICALL

軽量コールバックを作ります。 "Lightweight Callbacks" in perlcall を参照してください。

                MULTICALL;
POP_MULTICALL

軽量コールバックのための大かっこを閉じます。 "Lightweight Callbacks" in perlcall を参照してください。

                POP_MULTICALL;
PUSH_MULTICALL

軽量コールバックのための大かっこを開きます。 "Lightweight Callbacks" in perlcall を参照してください。

                PUSH_MULTICALL;

数値関数

grok_bin

2 進数を表現した文字列を数値形式に変換します。

エントリ start*len はスキャンする文字列を指定し、*flags は 変換フラグ、result は NULL か NV へのポインタです。 スキャンは文字列の末尾か、最初の不正な文字で停止します。 *flagsPERL_SCAN_SILENT_ILLDIGIT がセットされていなければ、不正な 文字に遭遇すると警告も引き起こされます。 返るときに、*len はスキャンした文字列の長さにセットされ、 *flags は出力フラグになります。

値が <= UV_MAX なら、出力フラグがクリアされ、*result に何も書かない UV として返されます。 値が > UV_MAX なら、grok_bin は出力フラグに PERL_SCAN_GREATER_THAN_UV_MAX をセットし、値を *result に書き込んで、 UV_MAX を返します (あるいは result が NULL なら値は捨てられます)。

エントリの *flagsPERL_SCAN_DISALLOW_PREFIX が セットされていなければ、2 進数にオプションとして "0b" または "b" を 前置できます。 *flagsPERL_SCAN_ALLOW_UNDERSCORES がセットされていると、2 進数で 数値を区切るのに '_' 文字が使えます。

        UV      grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
grok_hex

16 進数を表現した文字列を数値形式に変換します。

エントリ start*len はスキャンする文字列を指定し、*flags は 変換フラグ、result は NULL か NV へのポインタです。 スキャンは文字列の末尾か、最初の不正な文字で停止します。 *flagsPERL_SCAN_SILENT_ILLDIGIT がセットされていなければ、不正な 文字に遭遇すると警告も引き起こされます。 返るときに、*len はスキャンした文字列の長さにセットされ、 *flags は出力フラグになります。

値が <= UV_MAX なら、出力フラグがクリアされ、*result に何も書かない UV として返されます。 値が > UV_MAX なら、grok_hex は出力フラグに PERL_SCAN_GREATER_THAN_UV_MAX をセットし、値を *result に書き込んで、 UV_MAX を返します (あるいは result が NULL なら値は捨てられます)。

エントリの *flagsPERL_SCAN_DISALLOW_PREFIX が セットされていなければ、16 進数にオプションとして "0x" または "x" を 前置できます。 *flagsPERL_SCAN_ALLOW_UNDERSCORES がセットされていると、2 進数で 数値を区切るのに '_' 文字が使えます。

        UV      grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
grok_number

数値を認識します(またはしません)。 数値の型(認識されなかった場合は 0)が返され、さもなければ (perl.h に定義されている) IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN を ビット単位で OR したものです。

数値の値が UV に収まるなら、*valuep に返され、*valuep が有効であることを 示すために IS_NUMBER_IN_UV がセットされます; *valuep が有効でなければ IS_NUMBER_IN_UV がセットされることはありませんが、返る時点で IS_NUMBER_IN_UV がセットされていないとしても、処理中に *valuep に値が 代入されるかもしれません。 valuep が NULL なら、valuep が非 NULL の場合と同様に IS_NUMBER_IN_UV が セットされますが、実際の代入(または SEGV)は起こりません。

引き続く数字がある(この場合 *valuep には整数に切り詰められた真の値が入ります) の場合、IS_NUMBER_NOT_INT が IS_NUMBER_IN_UV と共にセットされ、値が負数 (この場合 *value には絶対値が入ります)の場合、IS_NUMBER_NEG が セットされます。 e 記法が使われたり数値が UV よりも大きいなら、IS_NUMBER_IN_UV は セットされません。

        int     grok_number(const char *pv, STRLEN len, UV *valuep)
grok_numeric_radix

小数点をスキャンして、読み飛ばします。

        bool    grok_numeric_radix(const char **sp, const char *send)
grok_oct

8 進数を表現した文字列を数値形式に変換します。

エントリ start*len はスキャンする文字列を指定し、*flags は 変換フラグ、result は NULL か NV へのポインタです。 スキャンは文字列の末尾か、最初の不正な文字で停止します。 *flagsPERL_SCAN_SILENT_ILLDIGIT がセットされていなければ、不正な 文字に遭遇すると警告も引き起こされます。 返るときに、*len はスキャンした文字列の長さにセットされ、 *flags は出力フラグになります。

値が <= UV_MAX なら、出力フラグがクリアされ、*result に何も書かない UV として返されます。 値が > UV_MAX なら、grok_oct は出力フラグに PERL_SCAN_GREATER_THAN_UV_MAX をセットし、値を *result に書き込んで、 UV_MAX を返します (あるいは result が NULL なら値は捨てられます)。

*flagsPERL_SCAN_ALLOW_UNDERSCORES が設定されると、8 進数は 数値を区切るのに '_' 文字を使えます。

        UV      grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
Perl_signbit

もし NV の符号ビットがセットされていれば非 0 の整数を、そうでなければ 0 を返します。

Configure は、このシステムの NV に動作する signbit() が持っていることを 検出します。 それから単にこれを perl.h の #define 経由で使います。 さもなければ、この実装にフォールバックします。 第 1 パスとして、これは -0.0 以外の全てを取ります。 悲しいかな、-0.0 の捕捉はこの関数の主な使用法なので、これはまだあまり 役には立ちません。 それでも、少なくとも便利であるとわかる他のシステムに対応する足場になります。

Configure の注意: この関数は、単なる 'signbit' ではなく 'Perl_signbit' と 呼ばれます; なぜなら たまたま NV の特定の選択で動作しない signbit() 関数やマクロを持つシステムを 想像するのは容易だからです。 単に signbit を Perl_signbit と再 #define して、標準システムヘッダがうまく 動くことを想定するべきではありません。 また、これは(pTHX_ なしの)コンテキストなし関数はありません; なぜなら Perl_signbit() は通常 perl.h でシステムの signbit() への単純なマクロ 呼び出しに再 #defined されるからです。 ユーザーは単に常に Perl_signbit() を呼び出してください。

注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。

        int     Perl_signbit(NV f)
scan_bin

後方互換性のためのものです。 代わりに grok_bin を使ってください。

        NV      scan_bin(const char* start, STRLEN len, STRLEN* retlen)
scan_hex

後方互換性のためのものです。 代わりに grok_hex を使ってください。

        NV      scan_hex(const char* start, STRLEN len, STRLEN* retlen)
scan_oct

後方互換性のためのものです。 代わりに grok_oct を使ってください。

        NV      scan_oct(const char* start, STRLEN len, STRLEN* retlen)

演算木操作関数

cv_const_sv

cv がインライン化可能な定数サブルーチンなら、サブルーチンから返される 定数値を返します。 さもなければ NULL を返します。

定数サブルーチンは newCONSTSUB か、"Constant Functions" in perlsub で 記述されている方法で作成されます。

        SV*     cv_const_sv(CV* cv)
newCONSTSUB

Perl での sub FOO () { 123 } と等価な定数サブルーチンを生成します。

        CV*     newCONSTSUB(HV* stash, const char* name, SV* sv)
newXS

Perl サブルーチンのように XSUB をフックするために xsubpp が使います。 filename は静的なストレージである必要があります; なぜならこれはコピーされることなく直接 CvFILE() で使われるからです。

パッドデータ構造体

pad_sv

現在のパッドのオフセット po の値を返します。 この関数を直接呼び出さずにマクロ PAD_SV を使ってください。

        SV*     pad_sv(PADOFFSET po)

インタプリタ単位変数

PL_modglobal

PL_modglobal は、汎用の、インタプリタグローバルの HV で、 インタプリタ毎の情報を保持するような エクステンションによって使われるものです。 場合によっては、データの共有をおこなうために エクステンションのシンボルテーブルとして使うことも可能です。 エクステンションのパッケージ名を、エクステンション固有のデータの名前の 接頭辞として使うのは良い考えです。

        HV*     PL_modglobal
PL_na

文字列の長さについて考慮しないような場合の SvPV と共に使われるような 変数です。 通常はローカル変数を宣言してそれを使うか、 SvPV_nolen マクロを使った方が効率が良いです。

        STRLEN  PL_na
PL_sv_no

これは false の SV です。 PL_sv_yes を参照してください。 常に &PL_sv_no として参照してください。

        SV      PL_sv_no
PL_sv_undef

これは undef SV です。 常に &PL_sv_undef として参照してください。

        SV      PL_sv_undef
PL_sv_yes

これは true SV です。 PL_sv_no を参照してくさい。 これは常に &PL_sv_yes として参照してください。

        SV      PL_sv_yes

正規表現関数

SvRX

SV から REGEXP を得るための便利なマクロです。 これはほぼ以下のコード片と等価です:

    if (SvMAGICAL(sv))
        mg_get(sv);
    if (SvROK(sv) &&
        (tmpsv = (SV*)SvRV(sv)) &&
        SvTYPE(tmpsv) == SVt_PVMG &&
        (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
    {
        return (REGEXP *)tmpmg->mg_obj;
    }

もし REGEXP* が見つからなければ NULL を返します。

        REGEXP *        SvRX(SV *sv)
SvRXOK

SV が qr magic (PERL_MAGIC_qr) を含んでいるかどうかを示す真偽値を返します。

後で REGEXP* で何かをしたいなら、代わりに SvRX を使って、NULL を チェックしてください。

        bool    SvRXOK(SV* sv)

単純な例外処理マクロ

dXCPT

例外処理のために必要なローカル変数を設定します。 "Exception Handling" in perlguts を参照してください。

                dXCPT;
XCPT_CATCH

catch ブロックを導入します。 "Exception Handling" in perlguts を参照してください。

XCPT_RETHROW

以前に捕捉した例外を再 throw します。 "Exception Handling" in perlguts を参照してください。

                XCPT_RETHROW;
XCPT_TRY_END

try ブロックを終了します。 "Exception Handling" in perlguts を参照してください。

XCPT_TRY_START

try ブロックを開始します。 "Exception Handling" in perlguts を参照してください。

スタック操作マクロ

dMARK

スタックマーカー変数 mark を XSUB のために宣言します。 MARKdORIGMARK を参照してください。

                dMARK;
dORIGMARK

XSUB のためのオリジナルのスタックマークを保存します。 ORIGMARK を参照してください。

                dORIGMARK;
dSP

マクロ SP を使ってアクセス可能な XSUB のためのスタックポインタのローカルな コピーを宣言します。 SP を参照してください。

                dSP;
EXTEND

XSUB の戻り値のために引数スタックを拡張するのに使われます。 一度使うと、少なくとも nitems をスタックにプッシュするだけの空きが 出来ます。

        void    EXTEND(SP, int nitems)
MARK

XSUB に対するスタックマーカーの変数です。 dMARK を参照してください。

mPUSHi

整数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルします。 TARG を使いません。 PUSHi, mXPUSHi, XPUSHi も参照してください。

        void    mPUSHi(IV iv)
mPUSHn

倍精度実数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルします。 TARG を使いません。 PUSHn, mXPUSHn, XPUSHn も参照してください。

        void    mPUSHn(NV nv)
mPUSHp

文字列をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 len は文字列の長さを示します。 'set' magic をハンドルします。 TARG を使いません。 PUSHp, mXPUSHp, XPUSHp も参照してください。

        void    mPUSHp(char* str, STRLEN len)
mPUSHu

符号なし整数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルします。 TARG を使いません。 PUSHu, mXPUSHu, XPUSHu も参照してください。

        void    mPUSHu(UV uv)
mXPUSHi

整数をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルします。 TARG を使いません。 XPUSHi, mPUSHi, PUSHi も参照してください。

        void    mXPUSHi(IV iv)
mXPUSHn

倍精度数値をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルします。 TARG を使いません。 XPUSHn, mPUSHn, PUSHn も参照してください。

        void    mXPUSHn(NV nv)
mXPUSHp

文字列をスタックにプッシュし、必要があればスタックを拡張します。 len は文字列の長さを示します。 'set' magic をハンドルします。 TARG を使いません。 XPUSHp, mPUSHp, PUSHp も参照してください。

        void    mXPUSHp(char* str, STRLEN len)
mXPUSHu

符号なし整数をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルします。 TARG を使いません。 XPUSHu, mPUSHu, PUSHu も参照してください。

        void    mXPUSHu(UV uv)
ORIGMARK

XSUB のためのオリジナルスタックマークです。 dORIGMARK を参照してください。

POPi

スタックから整数をポップします。

        IV      POPi
POPl

スタックから long をポップします。

        long    POPl
POPn

スタックから倍精度実数をポップします。

        NV      POPn
POPp

スタックから文字列をポップします。 廃止予定です。 新しいコードは POPpx を使うべきです。

        char*   POPp
POPpbytex

バイト列で構成されていなければならない(つまり文字 < 256 な)文字列を スタックからポップします。

        char*   POPpbytex
POPpx

スタックから文字列をポップします。

        char*   POPpx
POPs

スタックから SV をポップします。

        SV*     POPs
PUSHi

整数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mPUSHi を参照してください。 XPUSHimXPUSHi も参照してください。

        void    PUSHi(IV iv)
PUSHMARK

コールバックにある引数のためのブラケットを開きます。 PUTBACKperlcall を参照してください。

        void    PUSHMARK(SP)
PUSHmortal

新しい mortal SV をスタックへプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルしません。 TARG を使いません。 PUSHs, XPUSHmortal, XPUSHs も参照してください。

        void    PUSHmortal()
PUSHn

倍精度実数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mPUSHn を参照してください。 XPUSHnmXPUSHn も参照してください。

        void    PUSHn(NV nv)
PUSHp

文字列をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 len は文字列の長さを示します。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mPUSHp を参照してください。 XPUSHpmXPUSHp も参照してください。

        void    PUSHp(char* str, STRLEN len)
PUSHs

SV をスタックへプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルしません。 TARG を使いません。 PUSHmortal, XPUSHs, XPUSHmortal も参照してください。

        void    PUSHs(SV* sv)
PUSHu

符号なし整数をスタックにプッシュします。 スタックにはこの要素を収めるだけの空きがなければなりません。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mPUSHu を参照してください。 XPUSHumXPUSHu も参照してください。

        void    PUSHu(UV uv)
PUTBACK

XSUB 引数のためのブラケットを閉じます。 これは通常、xsubpp によって扱われます。 他の使い方については PUSHMARKperlcall を参照してください。

                PUTBACK;
SP

スタックポインタです。 これは通常、xsubpp によって扱われます。 dSPSPAGAIN を参照してください。

SPAGAIN

スタックポインタの再フェッチします。 コールバックの後で使われます。 perlcall を参照してください。

                SPAGAIN;
XPUSHi

整数をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mXPUSHi を参照してください。 PUSHimPUSHi も参照してください。

        void    XPUSHi(IV iv)
XPUSHmortal

揮発性の SV をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルしません。 TARG を使いません。 XPUSHs, PUSHmortal, PUSHs も参照してください。

        void    XPUSHmortal()
XPUSHn

倍精度数値をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mXPUSHn を参照してください。 PUSHnmPUSHn も参照してください。

        void    XPUSHn(NV nv)
XPUSHp

文字列をスタックにプッシュし、必要があればスタックを拡張します。 len は文字列の長さを示します。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mXPUSHp を参照してください。 PUSHpmPUSHp も参照してください。

        void    XPUSHp(char* str, STRLEN len)
XPUSHs

SV をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルしません。 TARG を使いません。 XPUSHmortal, PUSHs, PUSHmortal も参照してください。

        void    XPUSHs(SV* sv)
XPUSHu

符号なし整数をスタックにプッシュし、必要があればスタックを拡張します。 'set' magic をハンドルします。 TARG を使うので、これを宣言するために dTARGET または dXSTARG が 呼び出されるべきです。 XSUB からリストを返すために複数回 TARG 指向のマクロを 呼び出さないでください - 代わりに mXPUSHu を参照してください。 PUSHumPUSHu も参照してください。

        void    XPUSHu(UV uv)
XSRETURN

XSUB から戻され、スタックにあるアイテムの数を示します。 これは通常、xsubpp によって扱われます。

        void    XSRETURN(int nitems)
XSRETURN_EMPTY

XSUB から即座に空リストを返します。

                XSRETURN_EMPTY;
XSRETURN_IV

XSUB から即座に整数を返します。 XST_mIV を使います。

        void    XSRETURN_IV(IV iv)
XSRETURN_NO

XSUB から即座に &PL_sv_no を返します。 XST_mNO を使います。

                XSRETURN_NO;
XSRETURN_NV

XSUB から即座に倍精度数値を返します。 XST_mNV を使います。

        void    XSRETURN_NV(NV nv)
XSRETURN_PV

XSUB から即座に文字列のコピーを返します。 XST_mPV を使います。

        void    XSRETURN_PV(char* str)
XSRETURN_UNDEF

XSUB から即座に &PL_sv_undef を返します。 XST_mUNDEF を使います。

                XSRETURN_UNDEF;
XSRETURN_UV

XSUB から即座に整数を返します。 XST_mUV を使います。

        void    XSRETURN_UV(IV uv)
XSRETURN_YES

XSUB から即座に &PL_sv_yes を返します。 XST_mYES を使います。

                XSRETURN_YES;
XST_mIV

整数値をスタックの pos で指定される場所に置きます。 その値は新しい揮発性 SV (mortal SV) に格納されます。

        void    XST_mIV(int pos, IV iv)
XST_mNO

&PL_sv_no をスタックの pos で指定される場所に置きます。

        void    XST_mNO(int pos)
XST_mNV

倍精度数値をスタックの pos で指定される場所に置きます。 その値は新しい揮発性 SV (mortal SV) に格納されます。

        void    XST_mNV(int pos, NV nv)
XST_mPV

文字列のコピーをスタックの pos で指定される場所に置きます。 その値は新しい揮発性 SV (mortal SV) に格納されます。

        void    XST_mPV(int pos, char* str)
XST_mUNDEF

&PL_sv_undef をスタックの pos で指定される場所に置きます。

        void    XST_mUNDEF(int pos)
XST_mYES

&PL_sv_yes をスタックの pos で指定される場所に置きます。

        void    XST_mYES(int pos)

SV フラグ

svtype

Perl の型のためのフラグの列挙です。 sv.h というファイル中の svtype という列挙にあります。 これらのフラグは、SvTYPE というマクロを使って検査を行います。

SVt_IV

スカラに対する整数型。 svtype を参照してください。

SVt_NV

スカラに対する倍精度の型フラグ。 svtype を参照してください。

SVt_PV

スカラに対するポインタ型。 svtype を参照してください。

SVt_PVAV

配列に対する型フラグ。 svtype を参照してください。

SVt_PVCV

コードリファレンスのための型フラグ。 svtype を参照してください。

SVt_PVHV

ハッシュに対する型フラグ。 svtype を参照してください。

SVt_PVMG

blessされたスカラに対する型フラグ。 svtype を参照してください。

SV 操作関数

get_sv

指定された Perl スカラの SV を返します。 create がセットされていて、指定された変数が存在していなければ、 新たに生成されます。 create がセットされておらず、かつ、指定された変数がなかった場合には NULL が返されます。

注意: この関数の perl_ の形は廃止予定です。

        SV*     get_sv(const char* name, I32 create)
newRV_inc

SV に対する RV ラッパーを生成します。 元の SV の参照カウントはインクリメントされます。

        SV*     newRV_inc(SV* sv)
SvCUR

SV にある文字列の長さを返します。 SvLEN を参照してください。

        STRLEN  SvCUR(SV* sv)
SvCUR_set

SV にある文字列の現在の長さを設定します。 SvCUR を参照してください。

        void    SvCUR_set(SV* sv, STRLEN len)
SvEND

SV にある文字列の終端のキャラクタへのポインタを返します。 SvCUR を参照してください。 文字へは *(SvEND(sv)) としてアクセスします。

        char*   SvEND(SV* sv)
SvGAMAGIC

SV が get magic かオーバーロードであれば真を返します。 どちらかが真なら、スカラはアクティブなデータで、アクセスされる度に新しい値を 返す可能性があります。 従って、ユーザーの論理的な操作につき一回だけ読み込んで、返された値に対して 作業をするように注意しなければなりません。 どちらも真でなければ、書き込まれるまでスカラの値は変更できません。

        char*   SvGAMAGIC(SV* sv)
SvGROW

指定されたバイト数だけの空間があるように SV にある文字バッファを拡張します (予約分の空間は NUL 文字で埋められることを思い出してください)。 必要であれば、拡張のために sv_grow を呼び出します。 文字バッファへのポインタを返します。

        char *  SvGROW(SV* sv, STRLEN len)
SvIOK

SV が整数を含んでいるかどうかを表わす U32 値を返します。

        U32     SvIOK(SV* sv)
SvIOKp

SV が整数を含んでいるかどうかを表わす U32 値を返します。 private な設定を検査します。 SvIOK を使います。

        U32     SvIOKp(SV* sv)
SvIOK_notUV

SV が符号付き整数を含んでいるかどうかを示す真偽値を返します。

        bool    SvIOK_notUV(SV* sv)
SvIOK_off

SV の IV ステータスをアンセットします。

        void    SvIOK_off(SV* sv)
SvIOK_on

SV に対し、その SV が整数であるように指示します。

        void    SvIOK_on(SV* sv)
SvIOK_only

SV に対し、その SV が整数であり、他の OK ビットをすべてディセーブルに するように指示します。

        void    SvIOK_only(SV* sv)
SvIOK_only_UV

SV に対し、その SV が符号なし整数であり、他の OK ビットをすべてディセーブルに するように指示します。

        void    SvIOK_only_UV(SV* sv)
SvIOK_UV

SV が符号なし整数を含んでいるかどうかを示す真偽値を返します。

        bool    SvIOK_UV(SV* sv)
SvIsCOW

SV がコピーオンライトかどうかを示す真偽値を返します。 (共有ハッシュキースカラか、5.9.0 がコピーオンライト用に設定されていれば 完全なコピーオンライトスカラのどちらかです)

        bool    SvIsCOW(SV* sv)
SvIsCOW_shared_hash

SV が Copy-On-Write 共有ハッシュキースカラかどうかを示す真偽値を返します。

        bool    SvIsCOW_shared_hash(SV* sv)
SvIV

SV を強制的に整数に変換し、それを返します。 sv を一度だけ評価することが保証されているバージョンについては SvIVx を 参照してください。

        IV      SvIV(SV* sv)
SvIVX

SV の IV スロットの生の値を、チェックや変換なしに返します。 SvIOK が真であることを確認した後にのみ使えます。 SvIV() も参照してください。

        IV      SvIVX(SV* sv)
SvIVx

SV を強制的に整数に変換し、それを返します。 sv を一度だけ評価することを保証します。 sv が副作用のある式の時にのみこれを使ってください; さもなければより 効率的な SvIV を使ってください。

        IV      SvIVx(SV* sv)
SvIV_nomg

SvIV と同様ですが、magic を処理しません。

        IV      SvIV_nomg(SV* sv)
SvIV_set

sv の IV ポインタの値を val にセットします。 SvIVX への左辺値代入によってこのマクロと同じ機能を行うことが可能です。 しかし、将来の Perl では、SvIVX への左辺値代入の代わりに、SvIV_set を 使う方がより効率的になります。

        void    SvIV_set(SV* sv, IV val)
SvLEN

(SvOOK に起因する部分を含まない)SV にある文字列バッファのサイズを返します。 SvCUR を参照してください。

        STRLEN  SvLEN(SV* sv)
SvLEN_set

SV に含まれている文字列の実際の長さを設定します。 SvIV_set を参照してください。

        void    SvLEN_set(SV* sv, STRLEN len)
SvMAGIC_set

sv の MAGIC ポインタの値を val にセットします。 SvIV_set を参照してください。

        void    SvMAGIC_set(SV* sv, MAGIC* val)
SvNIOK

SV が数値、つまり整数値か倍精度実数値を含んでいるかどうかを表わす U32 値を返します。

        U32     SvNIOK(SV* sv)
SvNIOKp

SV が数値、つまり整数値か倍精度実数値を含んでいるかどうかを表わす U32 値を返します。 private な設定を検査します。 SvNIOK を使います。

        U32     SvNIOKp(SV* sv)
SvNIOK_off

SV の NT/IV ステータスをアンセットします。

        void    SvNIOK_off(SV* sv)
SvNOK

SV が倍精度実数値を含んでいるかどうかを示す U32 値を返します。

        U32     SvNOK(SV* sv)
SvNOKp

SV が倍精度実数値を含んでいるかどうかを示す U32 値を返します。 private な設定を検査します。 SvNOK を使います。

        U32     SvNOKp(SV* sv)
SvNOK_off

SV にある NT ステータスをアンセットします。

        void    SvNOK_off(SV* sv)
SvNOK_on

SV に対して、自分が倍精度実数であることを指示します。

        void    SvNOK_on(SV* sv)
SvNOK_only

SV に対し、その SV が倍精度実数であり、その他の OK フラグをディセーブルに するよう指示します。

        void    SvNOK_only(SV* sv)
SvNV

SV を強制的に倍精度数値に変換し、それを返します。 sv を一度しか評価されないことが保証されているバージョンについては SvNVx を参照してください。

        NV      SvNV(SV* sv)
SvNVX

SV の NV スロットの生の値を、チェックや変換なしに返します。 SvNOK が真であると分かっているときにだけ使ってください。 SvNV() も参照してください。

        NV      SvNVX(SV* sv)
SvNVx

SV を強制的に倍精度数値に変換し、それを返します。 sv を一度だけ評価することを保証します。 sv が副作用のある式の時にのみこれを使ってください; さもなければ より効率的な SvNV を使ってください。

        NV      SvNVx(SV* sv)
SvNV_set

sv の NV ポインタの値を val にセットします。 SvIV_set を参照してください。

        void    SvNV_set(SV* sv, NV val)
SvOK

値が SV であるかどうかを示す U32 値を返します。 これはまた、値が定義されているかどうかも知らせます。

        U32     SvOK(SV* sv)
SvOOK

SvIVX が SvPVX に対する正しいオフセット値であるかどうかを示す U32 値を 返します。 この hack は SvPV の先頭から文字を取り除くスピードを向上するために内部的に 使われます。 SvOOK が真であるとき、割り当てられた文字列バッファの開始点は (SvPVX - SvIVX)となります。

        U32     SvOOK(SV* sv)
SvPOK

SV が文字文字列を保持しているかどうかの U32 値を返します。

        U32     SvPOK(SV* sv)
SvPOKp

SV が文字文字列を保持しているかどうかの U32 値を返します。 private な設定を検査します。 SvPOK を使います。

        U32     SvPOKp(SV* sv)
SvPOK_off

SV の PV ステータスをアンセットします。

        void    SvPOK_off(SV* sv)
SvPOK_on

SV に対して、自分が文字列であることを指示します。

        void    SvPOK_on(SV* sv)
SvPOK_only

SV に対し、その SV が文字列であり、他の OK ビットをすべてディセーブルに するように指示します。 また、UTF-8 ステータスをオフにします。

        void    SvPOK_only(SV* sv)
SvPOK_only_UTF8

SV に対し、その SV が文字列であり、他の OK ビットをディセーブルに して、UTF-8 ステータスがそのままにするように指示します。

        void    SvPOK_only_UTF8(SV* sv)
SvPV

SV にある文字列へのポインタか、SVが文字列を保持していない場合には SV の文字列化形式を返します。 SV は SvPOK になった文字列化バージョンをキャッシュするかもしれません。 'get' magic をハンドルします。 sv が一度しか評価されないことが保証されているバージョンについては SvPVx も参照してください。

        char*   SvPV(SV* sv, STRLEN len)
SvPVbyte

SvPV と同様ですが、もし必要ならまず sv をバイト表現に変換します。

        char*   SvPVbyte(SV* sv, STRLEN len)
SvPVbytex

SvPV と同様ですが、もし必要ならまず sv をバイト表現に変換します。 sv を 1 度だけ評価することを保証します; さもなければより効率のよい SvPVbyte を使ってください。

        char*   SvPVbytex(SV* sv, STRLEN len)
SvPVbytex_force

SvPV_force と同様ですが、もし必要ならまず sv をバイト表現に変換します。 sv を 1 度だけ評価することを保証します; さもなければより効率のよい SvPVbyte_force を使ってください。

        char*   SvPVbytex_force(SV* sv, STRLEN len)
SvPVbyte_force

SvPV_force と同様ですが、もし必要ならまず sv をバイト表現に変換します。

        char*   SvPVbyte_force(SV* sv, STRLEN len)
SvPVbyte_nolen

SvPV_nolen と同様ですが、もし必要ならまず sv をバイト表現に変換します。

        char*   SvPVbyte_nolen(SV* sv)
SvPVutf8

SvPV と同様ですが、もし必要ならまず sv を utf8 に変換します。

        char*   SvPVutf8(SV* sv, STRLEN len)
SvPVutf8x

SvPV と同様ですが、もし必要ならまず sv を utf8 に変換します。 sv を 1 度だけ評価することを保証します; さもなければより効率のよい SvPVutf8 を使ってください。

        char*   SvPVutf8x(SV* sv, STRLEN len)
SvPVutf8x_force

SvPV_force と同様ですが、もし必要ならまず sv を utf8 に変換します。 sv を 1 度だけ評価することを保証します; さもなければより効率のよい SvPVutf8_force を使ってください。

        char*   SvPVutf8x_force(SV* sv, STRLEN len)
SvPVutf8_force

SvPV_force と同様ですが、もし必要ならまず sv を utf8 に変換します。

        char*   SvPVutf8_force(SV* sv, STRLEN len)
SvPVutf8_nolen

SvPV_nolen と同様ですが、もし必要ならまず sv を utf8 に変換します。

        char*   SvPVutf8_nolen(SV* sv)
SvPVX

SV にある物理文字列へのポインタを返します。 SV は文字列を保持していなければなりません。

        char*   SvPVX(SV* sv)
SvPVx

sv を一度だけ評価することを保証するバージョンの SvPV です。 sv が副作用のある式の時にのみこれを使ってください; さもなければ より効率的な SvPVV を使ってください。

        char*   SvPVx(SV* sv, STRLEN len)
SvPV_force

SvPV と同様ですが、SV が単に文字列(SvPOK_only)を含むことを強制します。 SvPVX を直接更新したい場合には強制したいでしょう。

        char*   SvPV_force(SV* sv, STRLEN len)
SvPV_force_nomg

SvPV と同様ですが、SV が単に文字列(SvPOK_only)を含むことを強制します。 SvPVX を直接更新したい場合には強制したいでしょう。 magic を処理しません。

        char*   SvPV_force_nomg(SV* sv, STRLEN len)
SvPV_nolen

SV にある文字列へのポインタか、SVが文字列を保持していない場合には SV の文字列化形式を返します。 SV は SvPOK になった文字列化形式をキャッシュするかもしれません。 'get' magic をハンドルします。

        char*   SvPV_nolen(SV* sv)
SvPV_nomg

SvPV と同様ですが、magic を処理しません。

        char*   SvPV_nomg(SV* sv, STRLEN len)
SvPV_set

sv の PV ポインタの値を val にセットします。 SvIV_set を参照してください。

        void    SvPV_set(SV* sv, char* val)
SvREFCNT

オブジェクトの参照カウントの値を返します。

        U32     SvREFCNT(SV* sv)
SvREFCNT_dec

SV で与えられたものの参照カウントを減じます。

        void    SvREFCNT_dec(SV* sv)
SvREFCNT_inc

SV で与えられたものの参照カウントを増やします。

以下の SvREFCNT_inc* マクロ全ては SvREFCNT_inc の最適化バージョンで、 SvREFCNT_inc に置き換えられます。

        SV*     SvREFCNT_inc(SV* sv)
SvREFCNT_inc_NN

SvREFCNT_inc と同じですが、sv が NULL ではないと分かっている場合にのみ 使えます。 NULL かどうかをチェックする必要がないので、より速くより小さいです。

        SV*     SvREFCNT_inc_NN(SV* sv)
SvREFCNT_inc_simple

SvREFCNT_inc と同じですが、式に副作用がない場合にのみ使えます。 一時的な値を保管する必要がないので、より速いです。

        SV*     SvREFCNT_inc_simple(SV* sv)
SvREFCNT_inc_simple_NN

SvREFCNT_inc_simple と同じですが、sv が NULL ではないと分かっている 場合にのみ使えます。 NULL かどうかをチェックする必要がないので、より速くより小さいです。

        SV*     SvREFCNT_inc_simple_NN(SV* sv)
SvREFCNT_inc_simple_void

SvREFCNT_inc_simple と同じですが、返り値が不要な場合にのみ使えます。 このマクロは意味のある値を返す必要はありません。

        void    SvREFCNT_inc_simple_void(SV* sv)
SvREFCNT_inc_simple_void_NN

SvREFCNT_inc と同じですが、返り値が不要で、sv が NULL ではないと 分かっている場合にのみ使えます。 このマクロは意味のある値を返す必要が無く、NULL をチェックする必要もないので、 より速くより小さいです。

        void    SvREFCNT_inc_simple_void_NN(SV* sv)
SvREFCNT_inc_void

SvREFCNT_inc と同じですが、返り値が不要な場合にのみ使えます。 このマクロは意味のある値を返す必要はありません。

        void    SvREFCNT_inc_void(SV* sv)
SvREFCNT_inc_void_NN

SvREFCNT_inc と同じですが、返り値が不要で、sv が NULL ではないと 分かっている場合にのみ使えます。 このマクロは意味のある値を返す必要が無く、NULL をチェックする必要もないので、 より速くより小さいです。

        void    SvREFCNT_inc_void_NN(SV* sv)
SvROK

SV が RV であるかを検査します。

        U32     SvROK(SV* sv)
SvROK_off

SV の RV ステータスをリセットします。

        void    SvROK_off(SV* sv)
SvROK_on

SV に、自分が RV であると指示します。

        void    SvROK_on(SV* sv)
SvRV

SV を返すために RV を参照はずしします。

        SV*     SvRV(SV* sv)
SvRV_set

sv の RV ポインタの値を val にセットします。 SvIV_set を参照してください。

        void    SvRV_set(SV* sv, SV* val)
SvSTASH

SV のスタッシュを返します。

        HV*     SvSTASH(SV* sv)
SvSTASH_set

sv の STASH ポインタの値を val にセットします。 SvIV_set を参照してください。

        void    SvSTASH_set(SV* sv, HV* val)
SvTAINT

汚染検査が有効なときに SV を汚染検査します。

        void    SvTAINT(SV* sv)
SvTAINTED

SV が汚染されているかどうかをチェックします。 汚染されていれば TRUE を、そうでなければ FALSE を返します。

        bool    SvTAINTED(SV* sv)
SvTAINTED_off

SV を汚染除去します。 Perl の基本的セキュリティ機構と同様 このルーチンを使うときは特に注意してください。 XS モジュールの作者は、汚染除去について良く理解しない限りは この関数を使うべきではありません。 perl 標準のやり方では直接変数の汚染除去するのではなく、 注意深く構築された正規表現を使って汚染除去が行われます。

        void    SvTAINTED_off(SV* sv)
SvTAINTED_on

汚染チェックが有効な場合、汚染されているという印を SV につけます。

        void    SvTAINTED_on(SV* sv)
SvTRUE

Perl が SV を真と評価するか偽と評価するか、define されているか undefine なのかを表わす真偽値を返します。 'set' magic をハンドルしません。

        bool    SvTRUE(SV* sv)
SvTYPE

SV の型を返します。 svtype を参照してください。

        svtype  SvTYPE(SV* sv)
SvUOK

SV が符号なし整数を含んでいるかどうかを示す真偽値を返します。

        bool    SvUOK(SV* sv)
SvUPGRADE

SV をより複雑なフォームにするために使われます。 必要であればアップグレードのために sv_upgrade を使用します。 svtype を参照してください。

        void    SvUPGRADE(SV* sv, svtype type)
SvUTF8

SV が UTF-8 エンコードされたデータを含んでいるかどうかを示す U32 値を 返します。 オーバーロードが内部フラグを更新する文字列に対して呼び出すときは SvPV() の後にこれを呼び出してください。

        U32     SvUTF8(SV* sv)
SvUTF8_off

SV の UTF-8 状態をリセットします。

        void    SvUTF8_off(SV *sv)
SvUTF8_on

SV の UTF-8 状態をオンにします (データは変更されません; フラグだけです)。 軽率に使わないでください。

        void    SvUTF8_on(SV *sv)
SvUV

SV を強制的に符号なし整数に変換し、それを返します。 sv が 1 度だけ評価されることを保証しているバージョンについては SvUVx を参照してください。

        UV      SvUV(SV* sv)
SvUVX

SV の UV スロットの生の値を、チェックや変換なしに返します。 SvIOK が真であることを確認した後にのみ使えます。 SvUV() も参照してください。

        UV      SvUVX(SV* sv)
SvUVx

SV を強制的に符号なし整数に変換し、それを返します。 sv を一度だけ評価することを保証します。 sv が副作用のある式の時にのみこれを使ってください; さもなければ より効率的な SvUV を使ってください。

        UV      SvUVx(SV* sv)
SvUV_nomg

SvUV と同様ですが、magic を処理しません。

        UV      SvUV_nomg(SV* sv)
SvUV_set

sv の UV ポインタの値を val にセットします。 SvIV_set を参照してください。

        void    SvUV_set(SV* sv, UV val)
SvVOK

SV がv-文字列を含んでいるかどうかを示す真偽値を返します。

        bool    SvVOK(SV* sv)
sv_catpvn_nomg

sv_catpvn と同様ですが、magic を処理しません。

        void    sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
sv_catsv_nomg

sv_catsv と同様ですが、magic を処理しません。

        void    sv_catsv_nomg(SV* dsv, SV* ssv)
sv_derived_from

C のレベルで SV が指定したクラスから派生したものであるかどうかを示す 真偽値を返します。 Perl レベルの派生をチェックするには、通常の Perl メソッドとして isa() を 呼び出してください。

        bool    sv_derived_from(SV* sv, const char* name)
sv_does

SV が特定の名前付きのロールを行うかどうかを示す真偽値を返します。 SV は Perl オブジェクトか Perl クラスの名前です。

        bool    sv_does(SV* sv, const char* name)
sv_report_used

開放されていない全ての SV の内容をダンプします。 (デバッグの助けとなります)。

        void    sv_report_used()
sv_setsv_nomg

sv_setsv と同様ですが、magic を処理しません。

        void    sv_setsv_nomg(SV* dsv, SV* ssv)

SV ボディ割り当て

looks_like_number

SV の内容が数値のようにみなせるか(あるいは数値であるか)を検査します。 たとえ atof() が認識しなくても、InfInfinity は数値として 扱われます(従って非数値警告は発生しません)。

        I32     looks_like_number(SV* sv)
newRV_noinc

SV に対する RV ラッパーを生成します。 元の SV の参照カウントはインクリメント されません

        SV*     newRV_noinc(SV* sv)
newSV

新たな SV を生成します。 非ゼロの len パラメーターは SV が持つべき割り当てずみ文字列空間の大きさを 示します。 余分な空間には NUL が埋められ、予約されます。 (SvPOK は文字列が割り当てられていたとしても SV をセットしません。) 新しい SV の参照カウントは 1 に設定されます。

5.9.3 で、newSV() は古い NEWSV() API を置き換え、呼び出し側が自分自身を 識別できるようにデバッグの助けをするための最初の引数 x がなくなりました。 この助けは新しいビルドオプション PERL_MEM_LOG ("PERL_MEM_LOG" in perlhack 参照) で置き換えられました。 古い API は、古い perl に対応している XS モジュールが使えるように まだ存在しています。

        SV*     newSV(STRLEN len)
newSVhek

ハッシュキー構造体から新しい SV を作成します。 可能なら共有文字列テーブルを指しているスカラを生成します。 hek が NULL なら、新しい(未定義値の) SV を返します。

        SV*     newSVhek(const HEK *hek)
newSViv

新たな SV を生成し、整数値をそこにコピーします。 SV の参照カウントは 1 に設定されます。

        SV*     newSViv(IV i)
newSVnv

新たな SV を生成し、不動小数点数値をそこにコピーします。 SV の参照カウントは 1 に設定されます。

        SV*     newSVnv(NV n)
newSVpv

新たな SV を生成し、文字列をそこにコピーします。 SV の参照カウントは 1 に設定されます。 len がゼロの場合、Perl が strlen() を使って長さを計算します。 効率のために、代わりに newSVpvn を使うことを考慮してください。

        SV*     newSVpv(const char* s, STRLEN len)
newSVpvf

新たな SV を生成し、sprintf のような文字列書式によって初期化します。

        SV*     newSVpvf(const char* pat, ...)
newSVpvn

新たな SV を生成し、文字列をそこにコピーします。 SV の参照カウントは 1 に設定されます。 len がゼロであった場合には長さゼロの文字列が生成されることに 注意してください。 ソース文字列が少なくとも len の長さがあることを保証する責任があります。 s 引数が NULL なら 新しい SV は未定義値です。

        SV*     newSVpvn(const char* s, STRLEN len)
newSVpvn_share

SvPVX_const が文字列テーブルの共有文字列を指している新しい SV を作成します。 文字列がまだテーブルに存在していないなら、まず作成されます。 READONLY と FAKE を有効にします。 hash 引数が非ゼロなら、その値が使われます; さもなければハッシュは 計算されます。 文字列のハッシュは、後で SvSHARED_HASH() マクロで SV から取得できます。 ここでの考え方は、文字列テーブルは共有ハッシュキーのために使われるので、 これらの文字列は SvPVX_const == HeKEY であって、ハッシュの検索は 文字列比較を防ぐと言うことです。

        SV*     newSVpvn_share(const char* s, I32 len, U32 hash)
newSVpvs

newSVpvn と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。

        SV*     newSVpvs(const char* s)
newSVpvs_share

newSVpvn_share と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取り、ハッシュパラメータを除外します。

        SV*     newSVpvs_share(const char* s)
newSVrv

SV を指し示す RV の rv に対する新たな SV を生成します。 rv が RV でない場合には、それは RV に昇格します。 classname がヌルでない場合には、生成された SV は指定されたパッケージに bless されます。 参照カウントが 1 に設定された SV が返されます。

        SV*     newSVrv(SV* rv, const char* classname)
newSVsv

元の SV を正確に複製した SV を生成します。 (sv_setsv を使います)。

        SV*     newSVsv(SV* old)
newSVuv

新しい SV を作成して、そこに符号なし整数をコピーします。 SV の参照カウントは 1 に設定されます。

        SV*     newSVuv(UV u)
newSV_type

指定された型の新しい SV を作成します。 新しい SV の参照カウントは 1 に設定されます。

        SV*     newSV_type(svtype type)
sv_2bool

この関数は magical なアイテムからのみ呼び出され、sv_true() や等価な マクロからのみ使われます。

        bool    sv_2bool(SV* sv)
sv_2cv

様々な作戦を使って、SV から CV を得ようとします; さらに、もし可能なら、 *st*gvp に、それと関連づけられているスタッシュと GV に セットしようとします。 lref のフラグは sv_fetchsv に渡されます。

        CV*     sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
sv_2io

様々な作戦を使って、SV から CV を得ようとします; GV なら IO スロット; RV なら再帰した結果; 文字列なら PV の後のシンボル名の IO スロットです。

        IO*     sv_2io(SV* sv)
sv_2iv_flags

必要な文字列変換を行って、SV の整数値を返します。 フラグに SV_GMAGIC が含まれていると、最初に mg_get() を行います。 通常は SvIV(sv)SvIVx(sv) マクロ経由で使われます。

        IV      sv_2iv_flags(SV* sv, I32 flags)
sv_2mortal

SV を揮発性にします。 SV は FREETMPS の明示的な呼び出しか、文の境界のような場所での暗黙の 呼び出しによって「すぐに」破壊されます。 この SV がコピーされると、SvTEMP() は SV の文字列バッファが「盗まれた」ことを 示すために音になります。 sv_newmortalsv_mortalcopy も参照してください。

        SV*     sv_2mortal(SV* sv)
sv_2nv

必要な文字列変換や整数変換、magic などを行って、SV の数値を返します。 通常は SvNV(sv)SvNVx(sv) のマクロ経由で使います。

        NV      sv_2nv(SV* sv)
sv_2pvbyte

SV のバイトエンコードされた表現へのポインタを返し、その長さを *lp に セットします。 副作用として、SV が UTF-8 から降格するかもしれません。

普通は SvPVbyte マクロ経由でアクセスされます。

        char*   sv_2pvbyte(SV* sv, STRLEN* lp)
sv_2pvutf8

SV の UTF-8 エンコードされた表現へのポインタを返し、その長さを *lp に セットします。 副作用として、SV が UTF-8 へ昇格するかもしれません。

普通は SvPVutf8 マクロ経由でアクセスされます。

        char*   sv_2pvutf8(SV* sv, STRLEN* lp)
sv_2pv_flags

SV の文字列値へのポインタを返し、*lp にその長さをセットします。 フラグに SV_GMAGIC が含まれていると、最初に mg_get() を行います。 必要なら sv を文字列に強制します。 通常は SvPV_flags マクロ経由で起動されます。 sv_2pv()sv_2pv_nomg も普通はここで終わります。

        char*   sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
sv_2uv_flags

必要な文字列変換を行って、SV の符号なし整数値を返します。 フラグに SV_GMAGIC が含まれていると、最初に mg_get() を行います。 通常は SvUV(sv)SvUVx(sv) マクロ経由で使われます。

        UV      sv_2uv_flags(SV* sv, I32 flags)
sv_backoff

文字列オフセットを取り除きます。 通常は代わりに SvOOK_off マクロラッパーを使うべきです。

        int     sv_backoff(SV* sv)
sv_bless

SV を指定したパッケージに bless します。 SV は RV でなければなりません。 パッケージは、そのスタッシュ(gv_stashpv() 参照)によって 指示されていなければなりません。 SV の参照カウントは影響を受けません。

        SV*     sv_bless(SV* sv, HV* stash)
sv_catpv

文字列を、SV にある文字列の終端に連結します。 SV の UTF-8 ステータスが設定されているなら、追加されるバイト列は妥当な UTF-8 であるべきです。 'get' magic をハンドルしますが、'set' magic はハンドルしません。 sv_catpv_mg を参照してください。

        void    sv_catpv(SV* sv, const char* ptr)
sv_catpvf

引数を sprintf のように処理し、SV にその結果を追加します。 追加するデータに「ワイド」文字(%s でフォーマットされた UTF-8 PV や %c でフォーマットされた >255 の文字の SV を含みますが、それに 限定されません)が含まれている場合、元の SV は UTF-8 に 昇格されるかもしれません。 'get' magic をハンドルしますが、'set' magic はハンドルしません。 sv_catpvf_mg を参照してください。 元の SV が UTF-8 なら、パターンは妥当な UTF-8 であるべきです; 元の SV が バイト列なら、パターンもそうあるべきです。

        void    sv_catpvf(SV* sv, const char* pat, ...)
sv_catpvf_mg

sv_catpvf と同様ですが、'set' magic もハンドルします。

        void    sv_catpvf_mg(SV *sv, const char* pat, ...)
sv_catpvn

文字列を、SV にある文字列の終端に連結します。 len はコピーするバイト数を示します。 SV の UTF-8 ステータスが設定されているなら、追加されるバイト列は妥当な UTF-8 であるべきです。 'get' magic をハンドルしますが、'set' magic はハンドルしません。 sv_catpvn_mg を参照してください。

        void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
sv_catpvn_flags

文字列を、SV にある文字列の終端に連結します。 len はコピーするバイト数を示します。 SV の UTF-8 ステータスが設定されているなら、追加されるバイト列は妥当な UTF-8 であるべきです。 flagsSV_GMAGIC ビットがセットされていると、適切なら dsvmg_get し、さもなければしません。 sv_catpvnsv_catpvn_nomg はこの関数に関して実装されています。

        void    sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
sv_catpvs

sv_catpvn と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。

        void    sv_catpvs(SV* sv, const char* s)
sv_catpv_mg

sv_catpv と同様ですが、'set' magic もハンドルします。

        void    sv_catpv_mg(SV *sv, const char *ptr)
sv_catsv

SV ssv にある文字列を、SV dsv にある文字列の終端へ連結します。 dsv を変更しますが ssv は変更しません。 'get' magic をハンドルしますが、'set' magic はハンドルしません。 sv_catsv_mg を参照してください。

        void    sv_catsv(SV* dsv, SV* ssv)
sv_catsv_flags

SV ssv にある文字列を、SV dsv にある文字列の終端へ連結します。 dsv を変更しますが ssv は変更しません。 flagsSV_GMAGIC ビットがセットされていると、適切なら SV に mg_get し、さもなければしません。 sv_catsvsv_catsv_nomg はこの関数に関して実装されています。

        void    sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
sv_chop

文字列バッファの先頭から文字を効率的に削除します。 SvPOK(sv) が真でなければならず、ptr は文字列バッファの 内側のどこかを指し示すポインタでなければなりません。 ptr は調整後の文字列の先頭となります。 "OOK hack" を使います。 注意: この関数から返った後、ptr と SvPVX_const(sv) はもはや同じデータの 塊を参照していません。

        void    sv_chop(SV* sv, const char* ptr)
sv_clear

SV をクリアします: デストラクタを呼び出し、ボディで使われたメモリを解放し、 ボディ自身を解放します。 SV のヘッダは解放 されません が、 its type is set to all 1's so that it won't inadvertently be assumed to be live during global destruction etc. この関数は REFCNT がゼロになったときにのみ呼び出されるべきです。 ほとんどの場合 sv_free() (またはそのマクロラッパー SvREFCNT_dec) を 呼び出したいでしょう。

        void    sv_clear(SV* sv)
sv_cmp

二つの SV にある文字列を比較します。 sv1sv2 より小さいときには -1 を、両者が等しいときには 0 を、 sv1sv2 より大きいときには 1 を返します。 UTF-8 と 'use bytes' を認識し、get magic をハンドルし、必要なら引数を 文字列に強制します。 sv_cmp_locale も参照してください。

        I32     sv_cmp(SV* sv1, SV* sv2)
sv_cmp_locale

ロケールを考慮した形で二つの SV の文字列を比較します。 UTF-8 と 'use bytes' を認識し、get magic をハンドルし、必要なら引数を 文字列に強制します。 sv_cmp_locale も参照してください。 sv_cmp も参照してください。

        I32     sv_cmp_locale(SV* sv1, SV* sv2)
sv_collxfrm

まだなければ、照合変換 magic を SV に追加します。

任意のスカラ値は変数のスカラデータを含む PERL_MAGIC_collxfrm magic を 保持しているかもしれませんが、ロケール設定に従った比較に通常のメモリ比較が 使えるようなフォーマットに変換されます。

        char*   sv_collxfrm(SV* sv, STRLEN* nxp)
sv_copypv

ソース SV の文字列化表現をデスティネーション SV にコピーします。 必要な mg_get と数値から文字列への強制を自動的に行います。 オーバーロードされたオブジェクトからであっても UTF8 フラグが 保存されることを保証します。 事実上 sv_2pv[_flags] と似ていますが、単なる文字列ではなく SV に対して 直接操作します。 この作業を行うためにほとんどは sv_2pv_flags フラグを使います; 例外は PV の UTF-8 性が失われるときです。

        void    sv_copypv(SV* dsv, SV* ssv)
sv_dec

SV にある値の自動デクリメントを行います; 必要なら文字列から数値への変換を 行います。 'get' magic をハンドルします。

        void    sv_dec(SV* sv)
sv_eq

二つの SV にある文字列が同一のものであるかどうかをあらわす真偽値を 返します。 UTF-8 と 'use bytes' を認識し、get magic をハンドルし、必要なら引数を 文字列に強制します。

        I32     sv_eq(SV* sv1, SV* sv2)
sv_force_normal_flags

SV に対する様々な種類のごまかしを元に戻します: PV が共有文字列なら、プライベートなコピーを作ります; 参照しているなら 参照を止めます; グロブなら、xpvmg に降格します; コピーオンライト スカラなら、コピーは書き込み時に行われ、ローカルに使われます。 SV_COW_DROP_PV がセットされているなら、コピーオンライトスカラは (もしあれば)PV バッファを落として、コピーを作る代わりに SvPOK_off に なります。 (このスカラが何か他の値にセットされようとした場所で使われます。) さらに、参照を止めるときに sv_unref_flags()flags 引数が 渡されます。 sv_force_normal は flags に 0 をセットしてこの関数を呼び出します。

        void    sv_force_normal_flags(SV *sv, U32 flags)
sv_free

SV の参照カウントをデクリメントして、ゼロになったら、デストラクタを起動して ボディによって使われているメモリを解放するために sv_clear を呼び出します; 最後に、SV のヘッド地震を割り当て解除します。 通常はラッパーマクロ SvREFCNT_dec 経由で呼び出されます。

        void    sv_free(SV* sv)
sv_gets

ファイルハンドルから 1 行読み込んで SV に保管し、オプションで既に 保管されている文字列に追記します。

        char*   sv_gets(SV* sv, PerlIO* fp, I32 append)
sv_grow

SV にある文字バッファを拡張します。 もし必要なら、sv_unref を使用して、SV を SVt_PV へ昇格します。 文字バッファへのポインタを返します。 代わりに SvGROW ラッパーを使用してください。

        char*   sv_grow(SV* sv, STRLEN newlen)
sv_inc

SV にある値の自動インクリメントを行います; もし必要なら、文字列から数値への変換を行います。 'get' magic をハンドルします。

        void    sv_inc(SV* sv)
sv_insert

文字列を、SV 中の指定されたオフセット/長さの位置に挿入します。 Perl の substr() 関数と同様のものです。

        void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, const char* little, STRLEN littlelen)
sv_isa

SV が指定したクラスに bless されているかどうかを表わす真偽値を 返します。 これは、subtype をどのようにチェックするかを知らないので、 継承関係に確認するのに sv_derived_from を使います。

        int     sv_isa(SV* sv, const char* name)
sv_isobject

SV が、bless されているオブジェクトを指す RV であるかどうかを表わす 真偽値を返します。 SV が RV でない場合、もしくはオブジェクトが bless されていない場合にはこれは false を返します。

        int     sv_isobject(SV* sv)
sv_len

SV にある文字列の長さを返します。 magic と型強制をハンドルします。 xpv_cur スロットへの生アクセスを提供する SvCUR も参照してください。

        STRLEN  sv_len(SV* sv)
sv_len_utf8

SV にある文字列の文字数を返します; ワイド UTF-8 バイトは一文字として 数えます。 magic と型強制をハンドルします。

        STRLEN  sv_len_utf8(SV* sv)
sv_magic

SV に magic を追加します。 必要ならまず sv を型 SVt_PVMG に昇格して、それから magic リストの 先頭に型 how の新しい magic アイテムを追加します。

namenamlen 引数の扱いに関する記述については (sv_magic が 呼び出す) sv_magicext を参照してください。

SvREADONLY SV に magic を追加したり同じ 'how' の複数の実体を追加するには sv_magicext を使う必要があります。

        void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
sv_magicext

SV に magic を追加して、必要なら昇格させます。 提供された vtable を適用して、追加した magic へのポインタを返します。

sv_magicext は、sv_magic が出来ないことが出来ると言うことに 注意してください。 特に、SvREADONLY SV に magic を追加したり、同じ 'how' の複数の実体を 追加したりできます。

namlen がゼロ以上なら、savepvnnameコピー が保管されます; namlen がゼロなら name はそのまま保管されて - もう一つの特殊な 場合として - (name && namlen == HEf_SVKEY) なら nameSV* を 含んでいるものと仮定されて、その REFCNT をインクリメントして、そのまま 保管されます。

(これは今では sv_magic によってサブルーチンとして使われます。)

        MAGIC * sv_magicext(SV* sv, SV* obj, int how, const MGVTBL *vtbl, const char* name, I32 namlen)
sv_mortalcopy

(sv_setsv を使って)元の SV のコピーである、新しい SV を生成します。 生成された SV は揮発性である目印が付けられます。 これは FREETMPS の明示的な呼び出しか、文の境界のような場所での暗黙の 呼び出しによって「すぐに」破壊されます。 sv_newmortalsv_2mortal も参照してください。

        SV*     sv_mortalcopy(SV* oldsv)
sv_newmortal

揮発性である新たな null SV を生成します。 新たに作られた SV の参照カウントは 1 に設定されます。 これは FREETMPS の明示的な呼び出しか、文の境界のような場所での暗黙の 呼び出しによって「すぐに」破壊されます。 sv_mortalcopysv_2mortal も参照してください。

        SV*     sv_newmortal()
sv_newref

SV の参照カウントをインクリメントします。 代わりに SvREFCNT_inc() ラッパーを使ってください。

        SV*     sv_newref(SV* sv)
sv_pos_b2u

文字列の先頭からバイト数で offsetp 離れたところから、UTF-8 文字として等価な 数の分だけ変換します。 magic と型強制をハンドルします。

        void    sv_pos_b2u(SV* sv, I32* offsetp)
sv_pos_u2b

文字列の先頭から UTF-8 の文字数で offsetp 離れたところから、 等価なバイト数の分だけのところまでの値を変換します; lenp が非ゼロなら、これは lenp と同じですが、この場合は文字列の 先頭からではなく offset から始めます。 magic と型強制をハンドルします。

        void    sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
sv_pvbyten_force

SvPVbytex_force マクロのバックエンドです。 代わりに、常にマクロを使ってください。

        char*   sv_pvbyten_force(SV* sv, STRLEN* lp)
sv_pvn_force

SV から何か識別できる文字列を取り出します。 複雑なマクロ式を扱えないコンパイラのための、SvPV_force マクロの プライベート実装です。 代わりに、常にマクロを使ってください。

        char*   sv_pvn_force(SV* sv, STRLEN* lp)
sv_pvn_force_flags

SV から何か識別できる文字列を取り出します。 flagsSV_GMAGIC ビットがセットされていると、適切なら svmg_get し、さもなければしません。 sv_pvn_forcesv_pvn_force_nomg はこの関数に関して実装されています。 通常は代わりに様々なラッパーマクロを使いたいでしょう: SvPV_forceSvPV_force_nomg を参照してください。

        char*   sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
sv_pvutf8n_force

SvPVutf8x_force マクロのバックエンドです。 代わりに、常にマクロを使ってください。

        char*   sv_pvutf8n_force(SV* sv, STRLEN* lp)
sv_reftype

SV がリファレンスしているものを記述した文字列を返します。

        const char*     sv_reftype(const SV* sv, int ob)
sv_replace

最初の引数を二つ目の引数のコピーにして、元のデータを削除します。 ターゲット SV は物理的にソース SV のボディの所有権を受け取って、フラグを 継承します; しかし、ターゲットは magic を保持したままで、ソースの magic は 捨てられます。 これは特殊な SV コピー操作であることに注意してください; ほとんどの場合 sv_setsv か多くのこれのマクロフロントエンドを使いたいでしょう。

        void    sv_replace(SV* sv, SV* nsv)
sv_reset

reset Perl 関数の基礎となる実装です。 perl レベルの関数は漠然と廃止予定であることに注意してください。

        void    sv_reset(const char* s, HV* stash)
sv_rvweaken

参照を弱めます: この RV の SvWEAKREF フラグをセットします; まだなければ 参照されている SB に PERL_MAGIC_backref magic を与えます; そしてこの RV への後方参照を magic と関連づけられた後方参照の配列に プッシュします。 RV がマジカルなら、set magic は RV がクリアした後呼び出されます。

        SV*     sv_rvweaken(SV *sv)
sv_setiv

整数を与えられた SV へコピーします; 必要なら最初に昇格します。 'set' magic をハンドルしません。 sv_setiv_mg も参照してください。

        void    sv_setiv(SV* sv, IV num)
sv_setiv_mg

sv_setiv と同様ですが、'set' magic をハンドルします。

        void    sv_setiv_mg(SV *sv, IV i)
sv_setnv

倍精度浮動小数点数を与えられた SV へコピーします; 必要なら最初に昇格します。 'set' magic をハンドルしません。 sv_setnv_mg も参照してください。

        void    sv_setnv(SV* sv, NV num)
sv_setnv_mg

sv_setnv と同様ですが、'set' magic をハンドルします。

        void    sv_setnv_mg(SV *sv, NV num)
sv_setpv

文字列を SV へコピーします。 文字列は null で終端されていなければなりません。 'set' magic をハンドルしません。 sv_setpv_mg を参照してください。

        void    sv_setpv(SV* sv, const char* ptr)
sv_setpvf

sv_catpvf のように動作しますが、SV にテキストを追加するのではなく コピーします。 'set' magic をハンドルしません。 sv_setpvf_mg を参照してください。

        void    sv_setpvf(SV* sv, const char* pat, ...)
sv_setpvf_mg

sv_setpvf と同様ですが、'set' magic をハンドルします。

        void    sv_setpvf_mg(SV *sv, const char* pat, ...)
sv_setpviv

整数値を与えられた SV をコピーし、同様にその文字列値を更新します。 'set' magic をハンドルしません。 sv_setpviv_mg を参照してください。

        void    sv_setpviv(SV* sv, IV num)
sv_setpviv_mg

sv_setpviv と同様ですが、'set' magic をハンドルします。

        void    sv_setpviv_mg(SV *sv, IV iv)
sv_setpvn

文字列を SV へコピーします。 パラメーター len はコピーされるバイト数を指示します。 ptr 引数が NULL なら SV は未定義値になります。 'set' magic をハンドルしません。 sv_setpvn_mg を参照してください。

        void    sv_setpvn(SV* sv, const char* ptr, STRLEN len)
sv_setpvn_mg

sv_setpvn と同様ですが、'set' magic をハンドルします。

        void    sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
sv_setpvs

sv_setpvn と同様ですが、文字列/長さの組ではなく、リテラルな文字列を 取ります。

        void    sv_setpvs(SV* sv, const char* s)
sv_setpv_mg

sv_setpv と同様ですが、'set' magic をハンドルします。

        void    sv_setpv_mg(SV *sv, const char *ptr)
sv_setref_iv

整数値を、bless することもできる新たな SV へコピーします。 引数 rv は RV へと昇格します。 この RV は新たな SV を指し示すように変更されます。 引数 classname は bless するパッケージを指示するものです。 bless をしないためには、classnameNULL をセットします。 新しい SV の参照カウントは 1 となり、RV が返されます。

        SV*     sv_setref_iv(SV* rv, const char* classname, IV iv)
sv_setref_nv

倍精度実数値を、bless することもできる新たな SV へコピーします。 引数 rv は RV へと昇格します。 この RV は新たな SV を指し示すように変更されます。 引数 classname は bless するパッケージを指示するものです。 bless をしないためには、classnameNULL をセットします。 新しい SV の参照カウントは 1 となり、RV が返されます。

        SV*     sv_setref_nv(SV* rv, const char* classname, NV nv)
sv_setref_pv

ポインタを、bless することもできる新たな SV へコピーします。 引数 rv は RV へと昇格します。 この RV は新たな SV を指し示すように変更されます。 引数 pv が NULL であれば、PL_sv_undef が新たな SV に格納されます。 引数 classname は bless するパッケージを指示するものです。 bless をしないためには、classnameNULL をセットします。 新しい SV の参照カウントは 1 となり、RV が返されます。

HV, AV, SV, CV のような Perl の他の type を使わないようにしてください; これは、そういったオブジェクトにポインタのコピー処理を 行うことでおかしくなってしまうからです。

sv_setref_pvn は、このポインタのコピーではなく文字列を コピーしているということに注意してください。

        SV*     sv_setref_pv(SV* rv, const char* classname, void* pv)
sv_setref_pvn

文字列を、bless することもできる新たな SV へコピーします。 文字列の長さを n で指定しなければなりません。 引数 rv は RV へと昇格します。 この RV は新たな SV を指し示すように変更されます。 引数 classname は bless するパッケージを指示するものです。 bless をしないためには、classnameNULL をセットします。 新しい SV の参照カウントは 1 となり、RV が返されます。

sv_setref_pv は、文字列をコピーするのではなくポインタを コピーするということに注意してください。

        SV*     sv_setref_pvn(SV* rv, const char* classname, const char* pv, STRLEN n)
sv_setref_uv

整数値を、bless することもできる新たな SV へコピーします。 引数 rv は RV へと昇格します。 この RV は新たな SV を指し示すように変更されます。 引数 classname は bless するパッケージを指示するものです。 bless をしないためには、classnameNULL をセットします。 新しい SV の参照カウントは 1 となり、RV が返されます。

        SV*     sv_setref_uv(SV* rv, const char* classname, UV uv)
sv_setsv

送り元の SV ssv の内容を、送り先の SV dsv にコピーします。 送り元の SV は、それが揮発性であった場合には破壊されるかもしれません; 従ってソース SV を再利用する必要がある場合にはこの関数は使わないでください。 'set' magic をハンドルしません。 大まかに言うと、送り先の以前の内容を消して、値としてのコピーを行います。

おそらく SvSetSV, SvSetSV_nosteal, SvSetMagicSV, SvSetMagicSV_nosteal のようなラッパーの一つを使いたいでしょう。

        void    sv_setsv(SV* dsv, SV* ssv)
sv_setsv_flags

送り元の SV ssv の内容を、送り先の SV dsv にコピーします。 送り元の SV は、それが揮発性であった場合には破壊されるかもしれません; 従って ソース SV を再利用する必要がある場合にはこの関数は使わないでください 'set' magic をハンドルしません。 大まかに言うと、送り先の以前の内容を消して、値としてのコピーを行います。 flagsSV_GMAGIC ビットがセットされていると、適切なら ssvmg_get し、さもなければしません。 flags 引数の NOSTEAL ビットがセットされているなら、temps の バッファは盗まれません。 <sv_setsv> と sv_setsv_nomg はこの関数に関して実装されています。

おそらく SvSetSV, SvSetSV_nosteal, SvSetMagicSV, SvSetMagicSV_nosteal のようなラッパーの一つを使いたいでしょう。

これはスカラをコピーする基本的な関数で、その他のほとんどのコピー的な 関数とマクロは基礎としてこれを使っています。

        void    sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
sv_setsv_mg

sv_setsv と同様ですが、'set' magic をハンドルします。

        void    sv_setsv_mg(SV *dstr, SV *sstr)
sv_setuv

符号なし整数を与えられた SV へコピーします; 必要ならまず昇格します。 'set' magic をハンドルしません。 sv_setuv_mg も参照してください。

        void    sv_setuv(SV* sv, UV num)
sv_setuv_mg

sv_setsv と同様ですが、'set' magic をハンドルします。

        void    sv_setuv_mg(SV *sv, UV u)
sv_tainted

SV の汚染を調べます。 代わりに SvTAINTED を使ってください。

        bool    sv_tainted(SV* sv)
sv_true

SV が Perl の規則で真の値を持っていれば真を返します。 sv_true() を呼び出すかも知れないし代わりにインライン版を使うかも知れない SvTRUE マクロを代わりに使ってください。

        I32     sv_true(SV *sv)
sv_unmagic

SV から type 型の全ての magic を取り除きます。

        int     sv_unmagic(SV* sv, int type)
sv_unref_flags

SV の RV ステータスをアンセットし、RV によって参照されているものの 参照カウントを減じます。 これは newSVrv の反転したものであると考えられます。 cflags 引数は、参照カウントをデクリメントすることを強制するために SV_IMMEDIATE_UNREF を含むことができます (さもなければデクリメントは参照カウントが 1 ではないか、読み込み専用 SV を 参照しているという条件で行われます)。 SvROK_off を参照してください。

        void    sv_unref_flags(SV* sv, U32 flags)
sv_untaint

Untaint an SV. Use SvTAINTED_off instead. void sv_untaint(SV* sv)

sv_upgrade

SV をより複雑な形式へと昇格させます。 一般的に新しいボディ型を SV に追加して、古いボディから出来るだけ多くの情報を コピーします。 一般的には SvUPGRADE マクロラッパーを使いたいでしょう。 svtype も参照してください。

        void    sv_upgrade(SV* sv, svtype new_type)
sv_usepvn_flags

自身の文字列値を得るのに ptr を使うように SV に指示します。 通常文字列は SV の内側に保管されますが、sv_usepvn によって SV が外側の 文字列を使えるようにできます。 ptrmalloc によって割り当てられたメモリを指しているべきです。 文字列の長さ len を指定しなければなりません。 デフォルトではこの関数は ptr で指されているメモリを realloc (つまり移動) するので、ポインタは sv_usepvn に与えられた後で解放されたりプログラマによって 使われたりするべきではありませんし、このポインタの「背後」(例えば ptr + 1) からのポインタを使うべきではありません。

flags & SV_SMAGIC が真なら、SvSETMAGIC を呼び出します。 flags & SV_HAS_TRAILING_NUL が真なら、ptr[len] は NUL で なければならず、realloc はスキップされます。 (つまりバッファは実際には少なくとも len より 1 バイト長く、既に SvPVX を保管する条件を満たしています。)

        void    sv_usepvn_flags(SV* sv, char* ptr, STRLEN len, U32 flags)
sv_utf8_decode

SV の PV が UTF-8 のオクテット並びで複数バイト文字を含んでいるなら、 文字のように見えるように SvUTF8 フラグがオンになります。 PV が単一バイト文字だけを含んでいるなら、SvUTF8 フラグはオフのママです。 PV の妥当性をスキャンして、PV が妥当な UTF-8 ではないなら偽を返します。

注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。

        bool    sv_utf8_decode(SV *sv)
sv_utf8_downgrade

SV の PV を文字からバイトに変換しようとします。 PV にバイトを超える文字が含まれているなら、この変換は失敗します; この場合、 偽を返すか、fail_ok が真でないなら、croak します。

これは汎用の Unicode からバイトエンコーディングへのインターフェースでは ありません: そのような目的には Encode エクステンションを使ってください。

注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。

        bool    sv_utf8_downgrade(SV *sv, bool fail_ok)
sv_utf8_encode

SV の PV を UTF-8 に変換しますが、再びオクテットのように見えるように SvUTF8 フラグをオフにします。

        void    sv_utf8_encode(SV *sv)
sv_utf8_upgrade

SV の PV を UTF-8 エンコードされた形式に変換します。 もしまだ行われていなければ、SV を文字列形式に強制します。 例え全てのバイトの最上位ビットがクリアされていても、将来の正当性チェックを 避けるために、常に SvUTF8 フラグがセットされます。

これは汎用のバイトエンコーディングから Unicode へのインターフェースでは ありません: そのような目的には Encode エクステンションを使ってください。

        STRLEN  sv_utf8_upgrade(SV *sv)
sv_utf8_upgrade_flags

SV の PV を UTF-8 エンコードされた形式に変換します。 もしまだ行われていなければ、SV を文字列形式に強制します。 例え全てのバイトの最上位ビットがクリアされていても、将来の正当性チェックを 避けるために、常に SvUTF8 フラグがセットされます。 flagsSV_GMAGIC ビットがセットされていると、適切なら svmg_get し、さもなければしません。 sv_utf8_upgradesv_utf8_upgrade_nomg はこの関数に関して 実装されています。

これは汎用のバイトエンコーディングから Unicode へのインターフェースでは ありません: そのような目的には Encode エクステンションを使ってください。

        STRLEN  sv_utf8_upgrade_flags(SV *sv, I32 flags)
sv_vcatpvf

引数を vsprintf のように処理してフォーマットした出力を SV に追加します。 'set' magic をハンドルしません。 sv_vcatpvf_mg を参照してください。

普通はフロントエンドである sv_catpvf 経由で使われます。

        void    sv_vcatpvf(SV* sv, const char* pat, va_list* args)
sv_vcatpvfn

引数を vsprintf のように処理してフォーマットした出力を SV に追加します。 C スタイルの変数引数リストがない(NULL)場合には Sv の配列を使用します。 汚染チェックが有効の状態で実行すると、(しばしばロケールの使用によって 結果が信頼できないものなら、maybe_tainted 経由で示します。

普通はフロントエンドである sv_vcatpvfsv_vcatpvf_mg 経由で 使われます。

        void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
sv_vcatpvf_mg

sv_vcatpvf と同様ですが、'set' magic をハンドルします。

普通はフロントエンドである sv_catpvf_mg 経由で使われます。

        void    sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args)
sv_vsetpvf

sv_vcatpvf と同様に動作しますが、追加するのではなく SV にテキストを コピーします。 'set' magic をハンドルしません。 sv_vsetpvf_mg を参照してください。

普通はフロントエンドである sv_setpvf 経由で使われます。

        void    sv_vsetpvf(SV* sv, const char* pat, va_list* args)
sv_vsetpvfn

vatpvfn のように動作しますが、SV にテキストを追加するのではなく コピーします。

普通はフロントエンドである sv_vsetpvfsv_vsetpvf_mg 経由で 使われます。

        void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
sv_vsetpvf_mg

sv_vsetpvf と同様ですが、'set' magic をハンドルします。

普通はフロントエンドである sv_setpvf_mg 経由で使われます。

        void    sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args)

Unicode 対応

bytes_from_utf8

長さ len の文字列 s を UTF-8 からバイトエンコーディングに変換します。 utf8_to_bytes と異なりますが bytes_to_utf8 と同様、 新しく作成された文字列へのポインタを返し、len を新しい長さで更新します。 変換が行われなければ元の文字列を返し、len は変更されません。 is_utf8 が 0 を指しているなら何もしません。 s が変換されたか、全て 7 ビット文字からなっている場合は is_utf8 を 0 にセットします。

注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。

        U8*     bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8)
bytes_to_utf8

長さ len の文字列 s を ASCII から UTF-8 エンコーディングに変換します。 新しく作成された文字列へのポインタを返し、len に新しい長さを 反映させます。

ASCII 以外のエンコーディングから UTF-8 に変換したいなら、 sv_recode_to_utf8() を参照してください。

注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。

        U8*     bytes_to_utf8(const U8 *s, STRLEN *len)
ibcmp_utf8

文字列 s1 と s2 が大文字小文字を無視しても違いがあれば真を返し、 さもなければ (大文字小文字を無視して同じなら) 偽を返します。 u1 が真なら、文字列 s1 は UTF-8 エンコードされた Unicode であると 仮定されます。 u2 が真なら、文字列 s2 は UTF-8 エンコードされた Unicode であると 仮定されます。 u1 か u2 が偽なら、対応する文字列はネイティブな 8 ビットエンコーディングで あると仮定されます。

pe1 と pe2 が非 NULL なら、スキャンポインタはここにコピーされます (これらは next 文字の先頭を指します)。 pe1 または pe2 の背後のポインタが非 NULL なら、これらはどのような場合でも スキャンが継続されないエンドポインタです。 バイト長 l1 と l2 が非ゼロなら、s1+l1 と s2+l2 がスキャンを停止して 成功したマッチングを定義するための条件となるゴール端ポインタとして 使われます: 明示的な長さを定義した全てのスキャンはマッチングが 成功するためにゴールポインタに到達しなければなりません)。

大文字小文字の虫に関して、Unicode の「畳み込み化」は文字の大文字化/小文字化の 両方の代わりに使われます; http://www.unicode.org/unicode/reports/tr21/ (Case Mappings) を 参照してください。

        I32     ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
is_utf8_char

任意の数のバイト列が妥当な UTF-8 文字から始まるかどうかをテストします。 INVARIANT (つまり ASCII) は妥当な UTF-8 文字であることに注意してください。 妥当であれば UTF-8 文字の実際のバイト数が返され、さもなければ 0 が 返されます。

        STRLEN  is_utf8_char(const U8 *p)
is_utf8_string

文字列の最初の len バイトが妥当な UTF-8 文字列なら真を返し、さもなければ 偽を返します。 「妥当な UTF-8 文字列」は「UTF-8 でエンコードされた、0x7F を超える符号位置の 文字を含む文字列」という意味ではないことに注意してください; なぜなら 妥当な ASCII 文字列は妥当な UTF-8 文字列だからです。

is_utf8_string_loclen() と is_utf8_string_loc() も参照してください。

        bool    is_utf8_string(const U8 *s, STRLEN len)
is_utf8_string_loc

is_utf8_string() と同様ですが、ep に、(「utf8 失敗」の場合)失敗した 位置を、(「utf8 成功」の場合) s+len の位置を保管します。

is_utf8_string_loclen() と is_utf8_string() も参照してください。

        bool    is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)
is_utf8_string_loclen

is_utf8_string() と同様ですが、ep に、(「utf8 失敗」の場合)失敗した 位置を、(「utf8 成功」の場合) s+len の位置を保管し、UTF-8 エンコードされた 文字の数を el に保管します。

is_utf8_string_loc() と is_utf8_string() も参照してください。

        bool    is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
pv_uni_display

スカラ dsv を文字列 spv 長さ len の表示可能なバージョンに構築します; 表示可能なバージョンは最大でも pvlim バイトの長さです (もしより長ければ、 残りは切り詰められて "..." が追加されます)。

flags 引数には、isPRINT() 可能な文字をそのまま表示する UNI_DISPLAY_ISPRINT、 \\[nrfta\\] を ('\n' のように) バックスラッシュ版として表示する UNI_DISPLAY_BACKSLASH を含むことができます (UNI_DISPLAY_BACKSLASH は \\ に関して UNI_DISPLAY_ISPRINT より優先されます)。 UNI_DISPLAY_QQ (およびその別名である UNI_DISPLAY_REGEX) は UNI_DISPLAY_BACKSLASH と UNI_DISPLAY_ISPRINT の両方をオンにします。

dsv の PV へのポインタが返されます。

        char*   pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
sv_cat_decode

encoding は Encode オブジェクトであると仮定して、また ssv の PV は そのエンコーディングのオクテットであると仮定して、入力のデコードは (PV + *offset) が指す位置から開始されます。 dsv は ssv からデコードされた UTF-8 文字列と連結されます。 デコードは文字列 str がデコード出力に現れるか、ssv の PV の入力が 終わったときに終了します。 オフセットが指す値は ssv の最後の入力位置によって修正されます。

終端子が見付かれば TRUE を、さもなければ FALSE を返します。

        bool    sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
sv_recode_to_utf8

encoding は Encode オブジェクトであると仮定して、また sv の PV のエントリは そのエンコーディングのオクテットであると仮定して、sv を Unicode (と UTF-8) に 変換します。

sv が既に UTF-8 なら(または POK でなければ)、あるいは encoding が リファレンスでなければ、sv に対して何もしません。 encoding が Encode::XS エンコーディングオブジェクトでなければ、 悪いことが起こります。 (lib/encoding.pmEncode を参照してください)。

sv の PV が返されます。

        char*   sv_recode_to_utf8(SV* sv, SV *encoding)
sv_uni_display

スカラ dsv をスカラ sv の表示可能なバージョンに構築します; 表示可能な バージョンは最大でも pvlim バイトの長さです (もしより長ければ、残りは 切り詰められて "..." が追加されます)。

flags 引数は pv_uni_display() と同様です。

dsv の PV へのポインタが返されます。

        char*   sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
to_utf8_case

"p" は、変換された UTF-8 文字列エンコーディングの文字へのポインタを 含みます。

"ustrp" は変換結果を入れた文字バッファへのポインタです。 "lenp" は結果の長さへのポインタです。

"swashp" は使う swash へのポインタです。

特殊と通常の両方のマッピングは lib/unicore/To/Foo.pl に保管され、 lib/utf8_heavy.pl を使って SWASHNEW によって読み込まれます。 特殊(普通は複数文字マッピングですが常にそうというわけではありません)を 先に試します。

「特殊」とは、ハッシュ %utf8::ToSpecLower を意味する "utf8::ToSpecLower" のような文字列です。 ハッシュへのアクセスは Perl_to_utf8_case() を通します。

「通常」とは、swash %utf8::ToLower を意味する "ToLower" のような文字列です。

        UV      to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, const char *normal, const char *special)
to_utf8_fold

p にある UTF-8 エンコードされた文字を畳み込み文字版に変換して、UTF-8 エンコードしたものを ustrp に、そのバイト数を lenp に保管します。 畳み込み文字版は元の文字より(最大 3 文字)長くなるかも知れないので、ustrp は 少なくとも UTF8_MAXBYTES_CASE+1 バイト必要であることに注意してください。

最初の文字の畳み込み文字版が返されます(しかし、上述の通り、もっとあるかも しれません。)

        UV      to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp)
to_utf8_lower

p にある UTF-8 エンコードされた文字を小文字版に変換して、UTF-8 エンコードしたものを ustrp に、そのバイト数を lenp に保管します。 小文字版は元の文字より長くなるかも知れないので、ustrp は少なくとも UTF8_MAXBYTES_CASE+1 バイト必要であることに注意してください。

最初の文字の小文字版が返されます(しかし、上述の通り、もっとあるかも しれません。)

        UV      to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp)
to_utf8_title

p にある UTF-8 エンコードされた文字をタイトル文字版に変換して、UTF-8 エンコードしたものを ustrp に、そのバイト数を lenp に保管します。 タイトル文字版は元の文字より長くなるかも知れないので、ustrp は少なくとも UTF8_MAXBYTES_CASE+1 バイト必要であることに注意してください。

最初の文字のタイトル文字版が返されます(しかし、上述の通り、もっとあるかも しれません。)

        UV      to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp)
to_utf8_upper

p にある UTF-8 エンコードされた文字を大文字版に変換して、UTF-8 エンコードしたものを ustrp に、そのバイト数を lenp に保管します。 小文字版は元の文字より長くなるかも知れないので、ustrp は少なくとも UTF8_MAXBYTES_CASE+1 バイト必要であることに注意してください。

最初の文字の大文字版が返されます(しかし、上述の通り、もっとあるかも しれません。)

        UV      to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp)
utf8n_to_uvchr

flags

UTF-8 エンコーディングされていると仮定されている文字列 s の最初の文字の ネイティブな符号位置を返します; retlen にはその文字のバイト数が セットされます。

長さとフラグは低レベルルーチンに渡されることを許しています。

        UV      utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
utf8n_to_uvuni

最低レベルの UTF-8 デコードルーチンです。 UTF-8 エンコーディングされていて curlen より長くはないと仮定されている 文字列 s の最初の文字のUnicode 符号位置を返します; retlen には その文字のバイト数がセットされます。

s が整形された UTF-8 文字を指していない場合、振る舞いは flags の値に 依存します: UTF8_CHECK_ONLY を含んでいれば、呼び出し側が警告を発生させて、 この関数は暗黙に retlen-1 にセットしてゼロを返すことを仮定します。 flags に UTF8_CHECK_ONLY が含まれていなければ、不正な文字に関する警告が 与えられ、retlen は想定される UTF-8 文字のバイト数がセットされ、ゼロが 返されます。

flags は、厳密な UTF-8 エンコーディングからの逸脱を認める様々なフラグを 含めることもできます (utf8.h を参照してください)。

ほとんどのコードではこれを直接呼び出さずに utf8_to_uvchr() を使うべきです。

        UV      utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
utf8_distance

UTF-8 ポインタ ab の間の UTF-8 文字の数を返します。

警告: ポインタが同じ UTF-8 バッファの中を指していることを「知っている」 場合にのみ使ってください。

        IV      utf8_distance(const U8 *a, const U8 *b)
utf8_hop

前または後ろに off 文字だけずらした UTF-8 ポインタ s を返します。

警告: offs で指されている UTF-8 データの内側であることと、 エントリ s が文字の最初のバイトか文字の最後のバイトの直後に 位置合わせされているということが「分かっている」場合以外は 使わないでください。

        U8*     utf8_hop(const U8 *s, I32 off)
utf8_length

UTF-8 文字エンコードされた文字列 s の文字数を返します。 e で停止します(これも含みます)。 e < s であったり、スキャンが e を超えて停止すると、croak します。

        STRLEN  utf8_length(const U8* s, const U8 *e)
utf8_to_bytes

長さ len の文字列 s を UTF-8 からバイトエンコーディングに変換します。 bytes_to_utf8 と違って、これは元の文字列を上書きし、新しい長さで len を 更新します。 失敗時にはゼロを返し、len に -1 をセットします。

文字列のコピーが必要なら、bytes_from_utf8 を参照してください。

注意: この関数は実験的で、予告なしに変更あるいは削除されるかもしれません。

        U8*     utf8_to_bytes(U8 *s, STRLEN *len)
utf8_to_uvchr

UTF-8 エンコーディングされていると仮定されている文字列 s の最初の文字の ネイティブな符号位置を返します; retlen にはその文字のバイト数が セットされます。

s が整形された UTF-8 文字を指していない場合、ゼロが返され、もし可能なら retlen は -1 がセットされます。

        UV      utf8_to_uvchr(const U8 *s, STRLEN *retlen)
utf8_to_uvuni

UTF-8 エンコーディングされていると仮定されている文字列 s の最初の文字の Unicode 符号位置を返します; retlen にはその文字のバイト数が セットされます。

この関数は、返された UV が Unicode 意味論テーブル (つまり swash) への インデックスとして考えられる場合にのみ使われるべきです。

s が整形された UTF-8 文字を指していない場合、ゼロが返され、もし可能なら retlen は -1 がセットされます。

        UV      utf8_to_uvuni(const U8 *s, STRLEN *retlen)
uvchr_to_utf8

ネイティブ符号位置 uv の UTF-8 表現を文字列 d の末尾に追加します; d は少なくとも UTF8_MAXBYTES+1 バイトの空きが必要です。 返り値は新しい文字の末尾の次のバイトへのポインタです。 言い換えると:

    d = uvchr_to_utf8(d, uv);

が、ネイティブな文字を認識した形で以下のようなことをするときの推奨する 方法です:

    *(d++) = uv;

        U8*     uvchr_to_utf8(U8 *d, UV uv)
uvuni_to_utf8_flags

Unicode 符号位置 uv の UTF-8 表現を文字列 d の末尾に追加します; d は少なくとも UTF8_MAXBYTES+1 バイトの空きが必要です。 返り値は新しい文字の末尾の次のバイトへのポインタです。 言い換えると:

    d = uvuni_to_utf8_flags(d, uv, flags);

または、ほとんどの場合では、

    d = uvuni_to_utf8(d, uv);

(これは以下と等価です)

    d = uvuni_to_utf8_flags(d, uv, 0);

というのものが、以下のようなものの Unicode を考慮に入れた方法として 推奨されます。

    *(d++) = uv;

        U8*     uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)

xsubpp および xsubpp 内部関数で作成された変数

ax

ST, XSprePUSH, XSRETURN マクロによって使われるスタックベース オフセットを示すために xsubpp によってセットアップされる変数。 dMARK マクロは MARK 変数をセットアップする前に 呼び出されなければなりません。

        I32     ax
CLASS

xsubpp によってセットアップされる、C++ の XS コンストラクターに 対するクラス名を表わす変数です。 これは常に char* です。 THIS を参照してください。

        char*   CLASS
dAX

ax 変数をセットアップします。 これは普通 dXSARGS を呼び出すことで xsubpp によって自動的に 扱われます。

                dAX;
dAXMARK

ax 変数とスタックマーカー変数 mark をセットアップします。 これは普通 dXSARGS を呼び出すことで xsubpp によって自動的に 扱われます。

                dAXMARK;
dITEMS

items 変数をセットアップします。 これは普通 dXSARGS を呼び出すことで xsubpp によって自動的に 扱われます。

                dITEMS;
dUNDERBAR

UNDERBAR を使いたい XSUB のために padoff_du 変数をセットアップします。

                dUNDERBAR;
dXSARGS

XSUB のために、スタックポインタとマークポインタをセットアップし、 dSP と dMARK を呼び出します。 dAXdITEMS を呼び出すことで変数 axitems を セットアップします。 これは通常、xsubpp によって自動的に扱われます。

                dXSARGS;
dXSI32

エイリアスを持つ XSUB のために変数 ix をセットアップします。 これは通常、xsubpp によって自動的に扱われます。

                dXSI32;
items

xsubpp によりセットアップされ、スタックにあるアイテムの数を表わす 変数です。 "Variable-length Parameter Lists" in perlxs を参照してください。

        I32     items
ix

xsubpp によりセットアップされ、それを起動するのに使われた XSUB の エイリアスを表わす変数です。 "The ALIAS: Keyword" in perlxs を参照してください。

        I32     ix
newXSproto

Perl サブルーチンのように XSUB をフックするために xsubpp が使います。 サブルーチンに対して Perl のプロトタイプを追加します。

RETVAL

xsubpp によってセットアップされ、XSUB の戻り値を保持する変数です。 これは、常に XSUB にとって正しい型になります。 "The RETVAL Variable" in perlxs を参照してください。

        (whatever)      RETVAL
ST

XSUB のスタック上にある要素にアクセスするために使われます。

        SV*     ST(int ix)
THIS

C++ の XSUB におけるオブジェクトを指定する、xsubpp によって設定される 変数です。 これは常に C++ オブジェクトとして適切な型です。 CLASS および "Using XS With C++" in perlxs を参照してください。

        (whatever)      THIS
UNDERBAR

$_ 変数に対応する SV*。 たとえスコープ内にレキシカルな $_ があっても動作します。

XS

XSUB とその C のパラメーターリストを宣言するためのマクロです。 これは xsubpp によって扱われます。

XS_VERSION

XS モジュールに対するバージョン識別子。 これは通常、ExtUtils::MakeMaker によって自動的に使われます。 XS_VERSION_BOOTCHECK を参照してください。

XS_VERSION_BOOTCHECK

PM モジュールのバージョン変数と、XS モジュールの XS_VERSION 変数とが マッチするかを検査するためのマクロです。 これは通常、xsubpp によって自動的に扱われます。 "The VERSIONCHECK: Keyword" in perlxs を参照してください。

                XS_VERSION_BOOTCHECK;

警告と die

croak

Perl の die 関数に対する XSUB 作成者のためのインターフェースです。 この関数は C の関数 printf と同じように呼び出します。 croak の呼び出しは制御を直ちに Perl に返し、通常の C の実行順序を 回避します。 warn を参照してください。

例外オブジェクトを投げたいなら、オブジェクトを $@ に代入してから、 croak() に NULL を渡します:

   errsv = get_sv("@", TRUE);
   sv_setsv(errsv, exception_object);
   croak(NULL);

        void    croak(const char* pat, ...)
warn

これは XSUB 作成者のための、Perl の warn 関数に対するインターフェースです。 この関数は C の関数 printf と同じように呼び出します。 croak() を参照してください。

        void    warn(const char* pat, ...)

AUTHORS

1997 年 5 月まで、このドキュメントは Jeff Okamoto <okamoto@corp.hp.com> によって管理されていました。 今では Perl 自身の一部として管理されています。

Dean Roehrich, Malcolm Beattie, Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, Stephen McCamant, Gurusamy Sarathy から多くの助力と提案を受けました。

元の API 一覧は Dean Roehrich <roehrich@cray.com> によるものです。

Benjamin Stuhl によって、ソースのコメントから自動生成するように 更新されました。

SEE ALSO

perlguts(1), perlxs(1), perlxstut(1), perlintern(1)