.\" 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 2014\-04\-06 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バイトを含めた値を指定する) 必要がある。

.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995
.\" and
.\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
バッファに \fIsize\fP バイトよりたくさん書き込もうとした場合には、エラーとなる。 (デフォルトでは、このようなエラーが見えるのは \fIstdio\fP
バッファがフラッシュされた時だけである。 \fIsetbuf(fp,\ NULL)\fP を使ってバッファリングを無効にする方法は、
出力操作を行った時点でエラーを検出するのに役立つ。 別の方法としては、 \fIsetbuffer(fp, buf, size)\fP
を使って、呼び出し側が明示的に stdio ストリームバッファとして \fIbuf\fP を指定し、バッファの指定時にバッファのサイズを stdio
に教える方法がある。)
.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.65 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。