5.6.1

名前

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 との共存

There is outline support for co-existence of PerlIO with stdio. Obviously if PerlIO is implemented in terms of stdio there is no problem. However if perlio is implemented on top of (say) sfio then mechanisms must exist to create a FILE * which can be passed to library code which is going to use stdio calls.

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”が $| の自動フラッシュに関係していないときにのみ これを使います)。

In addition to user API above there is an "implementation" interface which allows perl to get at internals of PerlIO. The following calls correspond to the various FILE_xxx macros determined by Configure. This section is really of interest to only those concerned with detailed perl-core behaviour or implementing a PerlIO mapping.

上述したユーザー 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_ptrPerlIO_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)

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