php_stream_make_seekable() は、まず origstream が シーク可能かどうか調べます。もしシークできない場合は、新たに一時的ストリーム を作り、元のストリームのデータをすべてそこにコピーします。 成功の場合は、newstream には、元のストリームが シーク可能だったとしても、常に利用可能なストリームが返されます。
flags で、どのような形のシーク可能なストリームが 返されるかを指定することができます。デフォルトのシーク可能なストリームを 利用したい場合は、PHP_STREAM_NO_PREFERENCE を (通常では動的に増大するメモリ上のバッファを利用するが、 もしストリーム内のデータが巨大な場合は、テンポラリファイルに裏打ちされた ストリームに切り替える)、または通常のテンポラリファイルに裏打ちされた ストリームを利用したい場合は、PHP_STREAM_PREFER_STDIO を指定してください。
表 44-1. php_stream_make_seekable() の返り値
| Value | Meaning |
|---|---|
| PHP_STREAM_UNCHANGED | 元のストリームがシーク可能だった。newstream には origstream がセットされます。 |
| PHP_STREAM_RELEASED | 元のストリームはシーク可能ではないので、開放された。 newstream には、新たに作成されたシーク可能なストリームがセットされます。 以後、origstream にアクセスしてはいけません。 |
| PHP_STREAM_FAILED | ストリームの変換中にエラーが発生した。 newstream には NULL がセットされます。 このとき origstream はまだ有効なストリームです。 |
| PHP_STREAM_CRITICAL | ストリームの変換中にエラーが発生し、元のストリームは origstream 不定な状態になっている。newstream には NULL がセットされます。このときは、origstream を閉じることを強く推奨します。 |
注意: 新しいストリームに対してシークを行い書き込みを行うような場合、 そのストリームは、必ずしも元のストリームと同じリソースに 関連付けられていると保証されているわけではないので、 この関数を呼び出す意味はあまりありません。
注意: もし、前方へのシークのみが必要なときは、この関数を利用してストリームを シーク可能にする必要はありません。ストリーム API は、 whence パラメータが SEEK_CUR の時、前方シークを エミュレートするからです。
注意: もし、origstream がネットワークベースのストリーム の場合は、この関数は、すべてのデータが読み込まれるまでブロックします。
注意: 絶対に、PHP スクリプト内で使用されているファイルポインタを参照する ストリームを、origstream に指定しないでください。 この関数は、そのストリームを閉じる場合があるので、スクリプト内で次に そのファイルポインタに対してアクセスが行われた場合に、クラッシュが 起こる可能性があります。
注意: ほとんどの場合において、この関数は、origstream が新たに開かれたストリームで、しかもストリーム層においてデータが バッファリングされていない時にのみ成功します。これにより、 また、この関数は正しく使うには多少複雑なので、できれば、 この関数を直接呼び出すのではなく、 php_stream_open_wrapper() を使い、 PHP_STREAM_MUST_SEEK をオプションとして渡す方法 を検討してみてください。