名前¶

書式¶

#include <stdio.h>
FILE *fmemopen(void *buf, size_t size, const char *mode);
FILE *open_memstream(char **ptr, size_t *sizeloc);
#include <wchar.h>
FILE *open_wmemstream(wchar_t **ptr, size_t *sizeloc);

glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照):

fmemopen(), open_memstream(), open_wmemstream():

説明¶

引き数 mode は fopen(3) の場合と同じである。 mode で追記モード (append mode) が指定された場合、ファイル位置の初期値は バッファー中の 最初のヌルバイト ('\0') の位置に設定される。 それ以外の場合は、ファイル位置の初期値はバッファーの先頭になる。 glibc 2.9 以降では、文字 'b' を mode の二番目の文字として指定 することができる。 この文字は「バイナリ」モードを指定するものである。 このモードでは、書き込み時に文字列終端のヌルバイトが黙って追加 される ことはない。また、 fseek(3) SEEK_END は、文字列の長さからの相対値 ではなく、バッファーの末尾 (size で指定した値) からの相対値となる。

書き込み用にオープンされたストリームをフラッシュ (fflush(3)) やクローズ (fclose(3)) した時に、 (バッファーに空きがあれば) ヌルバイトがバッファーの末尾に書き込まれる。 このようにするためには、呼び出し元は バッファーに 1バイト余裕を作る (size にこの 1バイトを含めた値を指定する) 必要がある。

バッファーに size バイトよりたくさん書き込もうとした場合には、エラーとなる。 (デフォルトでは、このようなエラーが見えるのは stdio バッファーがフラッシュされた時だけである。 以下の呼び出しを使ってバッファーリングを無効にする方法は、 出力操作を行った時点でエラーを検出するのに役立つ。

setbuf(stdream, NULL);

別の方法としては、 以下のように、 呼び出し側が明示的に stdio ストリームバッファーとして buf を指定し、バッファーの指定時にバッファーのサイズを stdio に教える方法がある。

setbuffer(stream, buf, size);

読み出し用にオープンされたストリームでは、 バッファー内にヌルバイト ('\0') があっても 読み出し操作がファイル末尾 (end-of-file) を返すことはない。 バッファーからの読み出しでファイル末尾が返るのは、 ファイルポインターがバッファーの先頭から size バイトを越えて先に進もうとした場合だけである。

buf に NULL が指定された場合、 fmemopen() は動的に size バイトの長さのバッファーを確保する。 この方法は、一時バッファーにデータの書き込みを行ってから、 その内容を再度読み出すようなアプリケーションで有用である。 このバッファーはストリームがクローズされるときに自動的に解放される。 呼び出し元からはこの関数が割り当てた一時バッファーへのポインター値を 知る方法は存在しない点に注意 (下記の open_memstream() も参照)。

open_memstream() 関数は、バッファーへの書き込み用にストリームをオープンする。 バッファーは (malloc(3) を使って) 動的に割り当てられ、必要に応じて自動的に伸長する。 ストリームをクローズした後で、呼び出し元はこのバッファーを free(3) すべきである。

このストリームが クローズ (fclose(3)) されたりフラッシュ (fflush(3)) された時に、 ptr と sizeloc の値はそれぞれバッファーへのポインターとそのサイズに更新される。 これらの値は、呼び出し元がそのストリームに新たな書き込みを 行わない場合に限り有効である。 ストリームに書き込みを行った際には、これらの変数を参照する前に ストリームを再度フラッシュしなければならない。

バッファー末尾のヌルバイトは保持される。 このヌルバイトは sizeloc に格納されるサイズには「含まれない」。

ストリームのファイル位置は fseek(3) や fseeko(3) で変更できる。 すでにデータが書き込まれた領域の末尾より先にファイル位置を動かすと、 その間の領域は 0 で埋められる。

open_wmemstream() は open_memstream() と同様だが、バイトではなくワイド文字に対して操作を行う点が異なる。

返り値¶

バージョン¶

準拠¶

POSIX.1-2008 では mode の 'b' は無視されるべきだと規定されて いる。一方、Technical Corrigendum (正誤表) 1 では、mode の 'b' が指定された場合の扱いは実装依存であることを許容するように 標準規格が修正されており、glibc の 'b' の扱いは許されている。

注意¶

バグ¶

size に 0 が指定された場合、 fmemopen() はエラー EINVAL で失敗 する。この場合にはストリームの作成に成功して、最初の読み出しを行った際に EOF (end of file) が返される方が、ストリームの扱いの一貫性が増すだろう。 また、 POSIX.1-2008 ではこの場合のエラーは規定されていない。

fmemopen() に追記モード ("a" や "a+") を指定すると、 ファイル位置の初期値は最初のヌルバイトに設定されるが、(ファイル オフセットをストリームの末尾以外の位置に再設定した場合)それ以降の 書き込みではストリームの末尾への追記が行われる訳ではない。

fmemopen() の mode 引き数に追記モード ("a" や "a+") を指定し、 size 引き数で指定した範囲の buf 内にヌルバイトがない場合、 POSIX.1-2008 では、ファイル位置の初期値はバッファーの末尾の直後の バイトに設定すべきとされている。しかし、glibc の fmemopen() では この場合ファイル位置は -1 に設定される。

fmemopen() でバイナリモードを指定するには、 'b' は mode の 2 文字目 でなければならない。 例えば、 "wb+" は意図通りの効果になるが、 "w+b" はそうではない。 これは fopen(3) の mode の扱いとは異なる。

glibc 2.9 での fmemopen() の「バイナリ」モードの追加は、 ABI (Application Binary Interface) が黙って変更された。 それ以前の fmemopen() では mode 内の 'b' は無視されていた。

例¶

$ ./a.out '1 23 43'
size=11; ptr=1 529 1849

#define _GNU_SOURCE
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#define handle_error(msg) \
    do { perror(msg); exit(EXIT_FAILURE); } while (0)
int
main(int argc, char *argv[])
{
    FILE *out, *in;
    int v, s;
    size_t size;
    char *ptr;
    if (argc != 2) {
        fprintf(stderr, "Usage: %s <file>\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    in = fmemopen(argv[1], strlen(argv[1]), "r");
    if (in == NULL)
        handle_error("fmemopen");
    out = open_memstream(&ptr, &size);
    if (out == NULL)
        handle_error("open_memstream");
    for (;;) {
        s = fscanf(in, "%d", &v);
        if (s <= 0)
            break;
        s = fprintf(out, "%d ", v * v);
        if (s == -1)
            handle_error("fprintf");
    }
    fclose(in);
    fclose(out);
    printf("size=%zu; ptr=%s\n", size, ptr);
    free(ptr);
    exit(EXIT_SUCCESS);
}

関連項目¶

この文書について¶