名前¶

perlapio - perl の入出力抽象インターフェース

概要¶

    PerlIO *PerlIO_stdin(void);
    PerlIO *PerlIO_stdout(void);
    PerlIO *PerlIO_stderr(void);

    PerlIO *PerlIO_open(const char *,const char *);
    int     PerlIO_close(PerlIO *);

    int     PerlIO_stdoutf(const char *,...)
    int     PerlIO_puts(PerlIO *,const char *);
    int     PerlIO_putc(PerlIO *,int);
    int     PerlIO_write(PerlIO *,const void *,size_t);
    int     PerlIO_printf(PerlIO *, const char *,...);
    int     PerlIO_vprintf(PerlIO *, const char *, va_list);
    int     PerlIO_flush(PerlIO *);

    int     PerlIO_eof(PerlIO *);
    int     PerlIO_error(PerlIO *);
    void    PerlIO_clearerr(PerlIO *);

    int     PerlIO_getc(PerlIO *);
    int     PerlIO_ungetc(PerlIO *,int);
    int     PerlIO_read(PerlIO *,void *,size_t);

    int     PerlIO_fileno(PerlIO *);
    PerlIO *PerlIO_fdopen(int, const char *);
    PerlIO *PerlIO_importFILE(FILE *, int flags);
    FILE   *PerlIO_exportFILE(PerlIO *, int flags);
    FILE   *PerlIO_findFILE(PerlIO *);
    void    PerlIO_releaseFILE(PerlIO *,FILE *);

    void    PerlIO_setlinebuf(PerlIO *);

    long    PerlIO_tell(PerlIO *);
    int     PerlIO_seek(PerlIO *,off_t,int);
    int     PerlIO_getpos(PerlIO *,Fpos_t *)
    int     PerlIO_setpos(PerlIO *,Fpos_t *)
    void    PerlIO_rewind(PerlIO *);

    int     PerlIO_has_base(PerlIO *);
    int     PerlIO_has_cntptr(PerlIO *);
    int     PerlIO_fast_gets(PerlIO *);
    int     PerlIO_canset_cnt(PerlIO *);

    char   *PerlIO_get_ptr(PerlIO *);
    int     PerlIO_get_cnt(PerlIO *);
    void    PerlIO_set_cnt(PerlIO *,int);
    void    PerlIO_set_ptrcnt(PerlIO *,char *,int);
    char   *PerlIO_get_base(PerlIO *);
    int     PerlIO_get_bufsiz(PerlIO *);

説明¶

Perl のソースコードでは、ANSI C の stdio.h にある関数ではなく 上記の関数を使うべきであり、perlio.h が Configure の実行時に選択した I/O 機構へ #define します。

これらの関数は stdio.h にあるものがモデルになっていますが、 それに渡すパラメーターは“ちょっとばかし整頓”されています。

PerlIO *

これは FILE * と似たものではありますが、FILE * と異なるのはこれが 不透明なものであるように扱うべきだということです (これが何かに対するポインターであると仮定するのが安全でしょう)。

PerlIO_stdin(), PerlIO_stdout(), PerlIO_stderr()

stdin, stdout, stderr の代わりに使ってください。 これらは変数でなく“関数呼び出し”のように記述されていますが、 これは使用するプラットフォームにおいてロードモジュールに対するデータの エクスポートができなかったり、あるいは異なる“スレッド”が異なる値を 持つ可能性があるといったときに、これらを関数呼び出しにするのが 簡単になるからです。

PerlIO_open(path, mode), PerlIO_fdopen(fd,mode)

対応する fopen()/fdopen() と同じ引数を取ります。

PerlIO_printf(f,fmt,...), PerlIO_vprintf(f,fmt,a)

fprintf()/vfprintf() と等価です。

PerlIO_stdoutf(fmt,...)

これは printf() と等価です。printf はこの関数に対する #define となっていますから、 (現時点では) Perl のソースコード中で printf(fmt,...) とすることは合法です。

PerlIO_read(f,buf,count), PerlIO_write(f,buf,count)

fread() および fwrite() に対応します。これらの引数がそれとは異なり、 “count”は一つだけしかなくて“file”が先頭であるということに 注意してください。

PerlIO_close(f)

PerlIO_puts(s,f), PerlIO_putc(c,f)

fputs() および fputc() に対応します。最初の引数に“file”が来るということに 注意してください。

PerlIO_ungetc(c,f)

ungetc() に対応します。最初の引数に“file”が来るということに注意してください。

PerlIO_getc(f)

getc() に対応します。

PerlIO_eof(f)

feof() に対応します。

PerlIO_error(f)

ferror()に対応します。

PerlIO_fileno(f)

fileno() に対応します。一部のプラットフォームにおいては、“fileno”の 意味するところがUNIXとは違うということに注意してください。

PerlIO_clearerr(f)

clearerr() に対応し、“ストリーム”の`eof'や`error'といったフラグを クリアします。

PerlIO_flush(f)

fflush() に対応します。

PerlIO_tell(f)

ftell() に対応します。

PerlIO_seek(f,o,w)

fseek() に対応します。

PerlIO_getpos(f,p), PerlIO_setpos(f,p)

それぞれ ftgetpos() と fsetpos() に対応します。 プラットフォームが stdio 呼び出しを持っていない場合にはこれらの関数は PerlIO_tell()、PerlIO_seek() によって実装されます。

PerlIO_rewind(f)

rewind() に対応します。一部の状況においてはこれは PerlIO_seek() によって 再定義されている可能性があるので注意してください。

PerlIO_tmpfile()

tmpfile() に対応し、クローズ時に自動的に削除される無名 PerlIO を返します。

stdio との共存¶

PerlIO と stdio との共存をサポートするためのアウトラインがあります。 PerlIO が stdio を使って実装されているのであれば、問題はありません。 しかし、perlio が sfio の上に実装されているのであれば stdio 呼び出しを 使おうとするライブラリコードに渡すことができる FILE * を作成する機構が なければなりません。

PerlIO_importFILE(f,flags)

Used to get a PerlIO * from a FILE *. May need additional arguments, interface under review.

FILE * から PerlIO * を得るのに使います。 追加の引数やインタフェースのレビューが必要です。

PerlIO_exportFILE(f,flags)

PerlIO * を取り、ANSI C の stdio.h のルーチンに渡して使われる ‘ネイティブ’な FILE * 構造体を返します。

‘export’された FILE * は記録され、それ以後のオリジナルの PerlIO * に対する PerlIO 操作に影響を及ぼす可能性があります。

PerlIO_findFILE(f)

直前の`export'された FILE * を(もしあれば)返します。インターフェースが 完全に定義されるまではこれはプレースホルダーです。

PerlIO_releaseFILE(p,f)

PerlIO_releaseFILE は、PerlIO にすべてのFILE * の使用が完了したことを知らせます。 完了したものは‘export’された FILE * のリストから削除されます。 そして、それに結び付けられている PerlIO * は元々の振る舞いに戻ります。

PerlIO_setlinebuf(f)

これは setlinebuf() に対応します。これを使うことは現時点では避けてください。 (Perl core は“dumping”が $| の自動フラッシュに関係していないときにのみ これを使います)。

上述したユーザー API に加えて、perl が PerlIO の内部で扱うことが できるようにする「実装」インターフェースがあります。 以下に挙げる呼び出しは、それぞれ Configure で定義される FILE_xxx マクロに 対応しています。 このセクションでは、perl-core の振る舞いや PerlIO のマッピングの 詳細についてのみ注目します。

PerlIO_has_cntptr(f)

“バッファ”中のカレントポジションへのポインターとバッファにある バイト数を返すことのできる実装です。

PerlIO_get_ptr(f)

バッファ中にある次の読み出し可能バイトへのポインターを返します。

PerlIO_get_cnt(f)

バッファ中の読み出すことのできるバイト数を返します。

PerlIO_canset_cnt(f)

バッファにあるバイト数を調整することのできる実装です。

PerlIO_fast_gets(f)

<FILE> 機構を取り扱うための perl の fast code を許すのに要求される インターフェースのすべてを実装しています。

  PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
                        PerlIO_canset_cnt(f) && \
                        `Can set pointer into buffer'

PerlIO_set_ptrcnt(f,p,c)

ポインターをバッファにセットし、バッファにあるバイト数はそのままです。 以前の PerlIO_get_ptr と PerlIO_get_cnt の呼び出しから 推測される範囲内のポインターをセットすることのみに使うべきでしょう。

PerlIO_set_cnt(f,c)

不明瞭 - バッファにあるバイト数をセットします。使うのはお薦めできません。 現在これは、doio.c でのみ count < -1 を 強制的に -1 にするために使われています。 おそらく PerlIO_set_empty やそれに類するものがあるべきでしょう。 この呼び出しは、“count”がポインターと“limit”から導き出される場合には 実際にはなにもしません。

PerlIO_has_base(f)

バッファを持っていて、バッファ全体へのポインターやその大きさを 返すことができる実装です。 -T/-Bテストのためにperlによって使われます。 そのほかのものは非常にはっきりしない形で使われます…

PerlIO_get_base(f)

バッファの開始位置を返します。

PerlIO_get_bufsiz(f)

バッファのトータルサイズを返します。