FUNOPEN(3)

名称
funopen, fropen, fwopen - ストリームのオープン

ライブラリ
libc

書式
#include <stdio.h> FILE * funopen(const void *cookie, int (*readfn)(void *, char *, int), int (*writefn)(void *, const char *, int), fpos_t (*seekfn)(void *, fpos_t, int), int (*closefn)(void *)) FILE * fropen(void *cookie, int (*readfn)(void *, char *, int)) FILE * fwopen(void *cookie, int (*writefn)(void *, const char *, int))

解説
funopen() 関数は、ストリームを最大 4 つの “I/O 関数” に関連付けます。 readfn か writefn のどちらかは必ず指定しなければなりません。 それ以外の箇所には適当な型の NULL ポインタを与えることができます。 これらの I/O 関数は、新しいストリームに対する 読込み、書込み、シーク、クローズのために使用されます。

通常、関数を省略したということは、 作成されたストリームに関連付けられた操作を実行すると失敗する、 ということを意味しています。 クローズ関数が省略されている場合は、 ストリームを閉じるとバッファリングされている出力がフラッシュされ、 成功して終了します。

readfn, writefn, seekfn, closefn の呼び出し規則は、それぞれ read(2), write(2), seek(2), close(2) のものと同じですが、通常ファイル記述子引数が置かれる場所に、 funopen() に指定された cookie 引数が渡されるという違いがあります。

読込みおよび書込み I/O 関数は、 setvbuf(3) を呼び出すことによって、 完全にバッファリングされたもしくは行単位でバッファリングされたストリームの 基礎となるバッファを変更することが許可されています。 バッファを完全に満たしたり完全に空にしたりすることまでは要求されません。 しかし、バッファリングされていない状態から バッファリングされた状態に変更したり、 行バッファのフラグの状態を変更したりすることは許可されていません。 最近指定された以外のバッファに対して読込みや書込みの呼び出しが 発生するということに備えておく必要があります。

すべてのユーザ I/O 関数は、-1 を返すことでエラーを報告することができます。 さらに、エラーが発生した場合、すべての関数は外部変数 errno を適切に設定する必要があります。

closefn() でのエラーは、ストリームを開いた状態には保持しません。

便宜を図るため、インクルードファイル <stdio.h> では、 funopen() を読込みまたは書込み関数だけを指定して呼び出す時のような、 fropen() マクロと fwopen() マクロが定義されています。

戻り値
成功して終了すると、 funopen() は FILE ポインタを返します。それ以外の場合では NULL が返され、エラーを示す値がグローバル変数 errno に設定されます。

エラー

[EINVAL]
    funopen() 関数が、読込み関数または書込み関数のどちらも指定されずに呼び出されました。 funopen() 関数は失敗した時に malloc(3) ルーチンのために指定されたエラーを errno に設定することもあります。

関連項目
fcntl(2), open(2), fclose(3), fopen(3), fseek(3), setbuf(3)

歴史
funopen() 関数は 4.4BSD に初めて現れました。

バグ
funopen() 関数は BSD 以外のシステムには移植可能でないかもしれません。