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 にあるものがモデルになっていますが、 それに渡すパラメーターは“ちょっとばかし整頓”されています。
これは FILE * と似たものではありますが、FILE * と異なるのはこれが 不透明なものであるように扱うべきだということです (これが何かに対するポインターであると仮定するのが安全でしょう)。
stdin, stdout, stderr の代わりに使ってください。
これらは変数でなく“関数呼び出し”のように記述されていますが、
これは使用するプラットフォームにおいてロードモジュールに対するデータの
エクスポートができなかったり、あるいは異なる“スレッド”が異なる値を
持つ可能性があるといったときに、これらを関数呼び出しにするのが
簡単になるからです。
対応する fopen()/fdopen() と同じ引数を取ります。
fprintf()/vfprintf() と等価です。
これは printf() と等価です。printf はこの関数に対する #define となっていますから、
(現時点では) Perl のソースコード中で printf(fmt,...) とすることは合法です。
fread() および fwrite() に対応します。これらの引数がそれとは異なり、 “count”は一つだけしかなくて“file”が先頭であるということに 注意してください。
fputs() および fputc() に対応します。最初の引数に“file”が来るということに 注意してください。
ungetc() に対応します。最初の引数に“file”が来るということに注意してください。
getc() に対応します。
feof() に対応します。
ferror()に対応します。
fileno() に対応します。一部のプラットフォームにおいては、“fileno”の 意味するところがUNIXとは違うということに注意してください。
clearerr() に対応し、“ストリーム”の`eof'や`error'といったフラグを クリアします。
fflush() に対応します。
ftell() に対応します。
fseek() に対応します。
それぞれ ftgetpos() と fsetpos() に対応します。 プラットフォームが stdio 呼び出しを持っていない場合にはこれらの関数は PerlIO_tell()、PerlIO_seek() によって実装されます。
rewind() に対応します。一部の状況においてはこれは PerlIO_seek() によって 再定義されている可能性があるので注意してください。
tmpfile() に対応し、クローズ時に自動的に削除される無名 PerlIO を返します。
(stdio との共存)
PerlIO と stdio との共存をサポートするためのアウトラインがあります。 PerlIO が stdio を使って実装されているのであれば、問題はありません。 しかし、perlio が sfio の上に実装されているのであれば stdio 呼び出しを 使おうとするライブラリコードに渡すことができる FILE * を作成する機構が なければなりません。
FILE * から PerlIO * を得るのに使います。 追加の引数やインタフェースのレビューが必要です。
PerlIO * を取り、ANSI C の stdio.h のルーチンに渡して使われる ‘ネイティブ’な FILE * 構造体を返します。
‘export’された FILE * は記録され、それ以後のオリジナルの PerlIO * に対する PerlIO 操作に影響を及ぼす可能性があります。
直前の`export'された FILE * を(もしあれば)返します。インターフェースが 完全に定義されるまではこれはプレースホルダーです。
PerlIO_releaseFILE は、PerlIO にすべてのFILE * の使用が完了したことを知らせます。 完了したものは‘export’された FILE * のリストから削除されます。 そして、それに結び付けられている PerlIO * は元々の振る舞いに戻ります。
これは setlinebuf() に対応します。これを使うことは現時点では避けてください。 (Perl core は“dumping”が $| の自動フラッシュに関係していないときにのみ これを使います)。
上述したユーザー API に加えて、perl が PerlIO の内部で扱うことが できるようにする「実装」インターフェースがあります。 以下に挙げる呼び出しは、それぞれ Configure で定義される FILE_xxx マクロに 対応しています。 このセクションでは、perl-core の振る舞いや PerlIO のマッピングの 詳細についてのみ注目します。
“バッファ”中のカレントポジションへのポインターとバッファにある バイト数を返すことのできる実装です。
バッファ中にある次の読み出し可能バイトへのポインターを返します。
バッファ中の読み出すことのできるバイト数を返します。
バッファにあるバイト数を調整することのできる実装です。
<FILE> 機構を取り扱うための perl の fast code を許すのに要求される インターフェースのすべてを実装しています。
PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
PerlIO_canset_cnt(f) && \
`Can set pointer into buffer'
ポインターをバッファにセットし、バッファにあるバイト数はそのままです。
以前の PerlIO_get_ptr と PerlIO_get_cnt の呼び出しから
推測される範囲内のポインターをセットすることのみに使うべきでしょう。
不明瞭 - バッファにあるバイト数をセットします。使うのはお薦めできません。 現在これは、doio.c でのみ count < -1 を 強制的に -1 にするために使われています。 おそらく PerlIO_set_empty やそれに類するものがあるべきでしょう。 この呼び出しは、“count”がポインターと“limit”から導き出される場合には 実際にはなにもしません。
バッファを持っていて、バッファ全体へのポインターやその大きさを 返すことができる実装です。 -T/-Bテストのためにperlによって使われます。 そのほかのものは非常にはっきりしない形で使われます…
バッファの開始位置を返します。
バッファのトータルサイズを返します。