.\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de),
.\" and Copyright 2005, 2012 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
.\" Distributed under the GPL.
.\" %%%LICENSE_END
.\"
.\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream()
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 2005, 2006 Akihiro MOTOKI
.\"                     all rights reserved.
.\" Translated 2005-12-26, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" Updated 2006-01-20, Akihiro MOTOKI
.\" Updated 2006-07-20, Akihiro MOTOKI
.\" Updated 2008-11-08, Akihiro MOTOKI, LDP v3.13
.\" Updated 2010-04-18, Akihiro MOTOKI, LDP v3.24
.\" Updated 2012-05-30, Akihiro MOTOKI <amotoki@gmail.com>
.\"
.TH FMEMOPEN 3 2015\-01\-22 GNU "Linux Programmer's Manual"
.SH 名前
fmemopen, open_memstream, open_wmemstream \- メモリーをストリームとしてオープンする
.SH 書式
.nf
\fB#include <stdio.h>\fP

\fBFILE *fmemopen(void *\fP\fIbuf\fP\fB, size_t \fP\fIsize\fP\fB, const char *\fP\fImode\fP\fB);\fP

\fBFILE *open_memstream(char **\fP\fIptr\fP\fB, size_t *\fP\fIsizeloc\fP\fB);\fP

\fB#include <wchar.h>\fP

\fBFILE *open_wmemstream(wchar_t **\fP\fIptr\fP\fB, size_t *\fP\fIsizeloc\fP\fB);\fP
.fi
.sp
.in -4n
glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
.in
.sp
\fBfmemopen\fP(), \fBopen_memstream\fP(), \fBopen_wmemstream\fP():
.PD 0
.ad l
.RS 4
.TP  4
glibc 2.10 以降:
_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
.TP 
glibc 2.10 より前:
_GNU_SOURCE
.RE
.ad
.PD
.SH 説明
\fBfmemopen\fP()  関数は、ストリームをオープンし、そのストリームに \fImode\fP で指定されたアクセス許可を設定する。
そのストリームを通じて、 \fIbuf\fP で指定された文字列やメモリーバッファーへの読み書きができる。 このバッファーは少なくとも \fIsize\fP
バイトの長さでなければならない。
.PP
引き数 \fImode\fP は \fBfopen\fP(3) の場合と同じである。 \fImode\fP で追記モード
(append mode) が指定された場合、ファイル位置の初期値は バッファー中の
最初のヌルバイト (\(aq\e0\(aq) の位置に設定される。
それ以外の場合は、ファイル位置の初期値はバッファーの先頭になる。
glibc 2.9 以降では、文字 \(aqb\(aq を \fImode\fP の二番目の文字として指定
することができる。 この文字は「バイナリ」モードを指定するものである。
このモードでは、書き込み時に文字列終端のヌルバイトが黙って追加 される
ことはない。また、 \fBfseek\fP(3) \fBSEEK_END\fP は、文字列の長さからの相対値
ではなく、バッファーの末尾 (\fIsize\fP で指定した値) からの相対値となる。
.PP
書き込み用にオープンされたストリームをフラッシュ (\fBfflush\fP(3))  やクローズ (\fBfclose\fP(3))  した時に、
(バッファーに空きがあれば) ヌルバイトがバッファーの末尾に書き込まれる。 このようにするためには、呼び出し元は バッファーに 1バイト余裕を作る
(\fIsize\fP にこの 1バイトを含めた値を指定する) 必要がある。

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

    setbuf(stdream, NULL);

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

    setbuffer(stream, buf, size);

.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995
.\" and
.\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
.PP
読み出し用にオープンされたストリームでは、 バッファー内にヌルバイト (\(aq\e0\(aq) があっても 読み出し操作がファイル末尾
(end\-of\-file) を返すことはない。 バッファーからの読み出しでファイル末尾が返るのは、 ファイルポインターがバッファーの先頭から
\fIsize\fP バイトを越えて先に進もうとした場合だけである。
.PP
\fIbuf\fP に NULL が指定された場合、 \fBfmemopen\fP()  は動的に \fIsize\fP バイトの長さのバッファーを確保する。
この方法は、一時バッファーにデータの書き込みを行ってから、 その内容を再度読み出すようなアプリケーションで有用である。
このバッファーはストリームがクローズされるときに自動的に解放される。 呼び出し元からはこの関数が割り当てた一時バッファーへのポインター値を
知る方法は存在しない点に注意 (下記の \fBopen_memstream\fP()  も参照)。

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

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

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

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

\fBopen_wmemstream\fP()  は \fBopen_memstream\fP()
と同様だが、バイトではなくワイド文字に対して操作を行う点が異なる。
.SH 返り値
成功して終了した場合には、 \fBfmemopen\fP(), \fBopen_memstream\fP(), \fBopen_wmemstream\fP()  は
\fIFILE\fP ポインターを返す。 失敗した場合は、 NULL を返し、 \fIerrno\fP にエラーを示す値をセットする。
.SH バージョン
\fBfmemopen\fP()  と \fBopen_memstream\fP()  は glibc 1.0.x ですでに利用可能であった。
\fBopen_wmemstream\fP()  は glibc 2.4 以降で利用可能である。
.SH 準拠
POSIX.1\-2008.  これらの関数は POSIX.1\-2001 では規定れていないが、 Linux 以外のシステムで広く利用可能である。

.\" http://austingroupbugs.net/view.php?id=396
POSIX.1\-2008 では \fImode\fP の \(aqb\(aq は無視されるべきだと規定されて
いる。一方、Technical Corrigendum (正誤表) 1 では、\fImode\fP の
\(aqb\(aq が指定された場合の扱いは実装依存であることを許容するように
標準規格が修正されており、glibc の \(aqb\(aq の扱いは許されている。
.SH 注意
これらの関数が返すファイルストリームに対応するファイル ディスクリプターはない (つまり、返されたストリームに対して \fBfileno\fP(3)
を呼び出すとエラーが返ることになる)。
.SH バグ
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
バージョン 2.7 より前の glibc では、 \fBopen_memstream\fP()
で作成されたストリームの末尾より先にファイル位置を動かしても、 バッファーが伸長されず、 \fBfseek\fP(3)  が失敗し \-1 が返る。

.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=11216
\fIsize\fP に 0 が指定された場合、 \fBfmemopen\fP() はエラー \fBEINVAL\fP で失敗
する。この場合にはストリームの作成に成功して、最初の読み出しを行った際に
EOF (end of file) が返される方が、ストリームの扱いの一貫性が増すだろう。
また、 POSIX.1\-2008 ではこの場合のエラーは規定されていない。

.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13152
\fBfmemopen\fP() に追記モード ("a" や "a+") を指定すると、
ファイル位置の初期値は最初のヌルバイトに設定されるが、(ファイル
オフセットをストリームの末尾以外の位置に再設定した場合)それ以降の
書き込みではストリームの末尾への追記が行われる訳ではない。

.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13151
\fBfmemopen\fP() の \fImode\fP 引き数に追記モード ("a" や "a+") を指定し、
\fIsize\fP 引き数で指定した範囲の \fIbuf\fP 内にヌルバイトがない場合、
POSIX.1\-2008 では、ファイル位置の初期値はバッファーの末尾の直後の
バイトに設定すべきとされている。しかし、glibc の \fBfmemopen\fP() では
この場合ファイル位置は \-1 に設定される。

.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12836
\fBfmemopen\fP() でバイナリモードを指定するには、
\(aqb\(aq は \fImode\fP の \fI2 文字目\fP でなければならない。
例えば、 "wb+" は意図通りの効果になるが、 "w+b" はそうではない。
これは \fBfopen\fP(3) の \fImode\fP の扱いとは異なる。

.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544
glibc 2.9 での \fBfmemopen\fP() の「バイナリ」モードの追加は、
ABI (Application Binary Interface) が黙って変更された。
それ以前の \fBfmemopen\fP() では \fImode\fP 内の \(aqb\(aq は無視されていた。
.SH 例
このプログラムは \fBfmemopen\fP()  を使って出力バッファーをオープンし、 \fBopen_memstream\fP()
を使って動的にサイズが変化する出力バッファーをオープンしている。 (プログラムの第一コマンドライン引き数から取った) 入力文字列を
スキャンして整数を読み込み、これらの整数の二乗を出力バッファーに書き出す。 このプログラムの実行例は以下のようになる。
.in +4n
.nf

$\fB ./a.out \(aq1 23 43\(aq\fP
size=11; ptr=1 529 1849
.fi
.in
.SS プログラムのソース
\&
.nf
#define _GNU_SOURCE
#include <string.h>
#include <stdio.h>
#include <stdlib.h>

#define handle_error(msg) \e
    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>\en", 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\en", size, ptr);
    free(ptr);
    exit(EXIT_SUCCESS);
}
.fi
.SH 関連項目
\fBfopen\fP(3), \fBfopencookie\fP(3)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。