release/man3/fmemopen.3

   1 .\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de),
   2 .\" and Copyright 2005, 2012 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   5 .\" Distributed under the GPL.
   6 .\" %%%LICENSE_END
   7 .\"
   8 .\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream()
   9 .\"
  10 .\"*******************************************************************
  11 .\"
  12 .\" This file was generated with po4a. Translate the source file.
  13 .\"
  14 .\"*******************************************************************
  15 .TH FMEMOPEN 3 2012\-04\-28 GNU "Linux Programmer's Manual"
  16 .SH 名前
  17 fmemopen, open_memstream, open_wmemstream \- メモリをストリームとしてオープンする
  18 .SH 書式
  19 .nf
  20 \fB#include <stdio.h>\fP
  21
  22 \fBFILE *fmemopen(void *\fP\fIbuf\fP\fB, size_t \fP\fIsize\fP\fB, const char *\fP\fImode\fP\fB);\fP
  23
  24 \fBFILE *open_memstream(char **\fP\fIptr\fP\fB, size_t *\fP\fIsizeloc\fP\fB);\fP
  25
  26 \fB#include <wchar.h>\fP
  27
  28 \fBFILE *open_wmemstream(wchar_t **\fP\fIptr\fP\fB, size_t *\fP\fIsizeloc\fP\fB);\fP
  29 .fi
  30 .sp
  31 .in -4n
  32 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  33 .in
  34 .sp
  35 \fBfmemopen\fP(), \fBopen_memstream\fP(), \fBopen_wmemstream\fP():
  36 .PD 0
  37 .ad l
  38 .RS 4
  39 .TP  4
  40 glibc 2.10 以降:
  41 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  42 .TP
  43 glibc 2.10 より前:
  44 _GNU_SOURCE
  45 .RE
  46 .ad
  47 .PD
  48 .SH 説明
  49 \fBfmemopen\fP()  関数は、ストリームをオープンし、そのストリームに \fImode\fP で指定されたアクセス許可を設定する。
  50 そのストリームを通じて、 \fIbuf\fP で指定された文字列やメモリバッファへの読み書きができる。 このバッファは少なくとも \fIsize\fP
  51 バイトの長さでなければならない。
  52 .PP
  53 引き数 \fImode\fP は \fBfopen\fP(3) の場合と同じである。 \fImode\fP で追記モード
  54 (append mode) が指定された場合、ファイル位置の初期値は バッファ中の
  55 最初の NULL バイト (\(aq\e0\(aq) の位置に設定される。
  56 それ以外の場合は、ファイル位置の初期値はバッファの先頭になる。
  57 glibc 2.9 以降では、文字 \(aqb\(aq を \fImode\fP の二番目の文字として指定
  58 することができる。 この文字は「バイナリ」モードを指定するものである。
  59 このモードでは、書き込み時に文字列終端のヌルバイトが黙って追加 される
  60 ことはない。また、 \fBfseek\fP(3) \fBSEEK_END\fP は、文字列の長さからの相対値
  61 ではなく、バッファの末尾 (\fIsize\fP で指定した値) からの相対値となる。
  62 .PP
  63 書き込み用にオープンされたストリームをフラッシュ (\fBfflush\fP(3))  やクローズ (\fBfclose\fP(3))  した時に、
  64 (バッファに空きがあれば) NULL バイトがバッファの末尾に書き込まれる。 このようにするためには、呼び出し元は バッファに 1バイト余裕を作る
  65 (\fIsize\fP にこの 1バイトを含めた値を指定する) 必要がある。
  66
  67 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995
  68 .\" and
  69 .\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
  70 バッファに \fIsize\fP バイトよりたくさん書き込もうとした場合には、エラーとなる。 (デフォルトでは、このようなエラーが見えるのは \fIstdio\fP
  71 バッファがフラッシュされた時だけである。 \fIsetbuf(fp,\ NULL)\fP を使ってバッファリングを無効にする方法は、
  72 出力操作を行った時点でエラーを検出するのに役立つ。 別の方法としては、 \fIsetbuffer(fp, buf, size)\fP
  73 を使って、呼び出し側が明示的に stdio ストリームバッファとして \fIbuf\fP を指定し、バッファの指定時にバッファのサイズを stdio
  74 に教える方法がある。)
  75 .PP
  76 読み出し用にオープンされたストリームでは、 バッファ内に NULL バイト (\(aq\e0\(aq) があっても 読み出し操作がファイル末尾
  77 (end\-of\-file) を返すことはない。 バッファからの読み出しでファイル末尾が返るのは、 ファイルポインタがバッファの先頭から \fIsize\fP
  78 バイトを越えて先に進もうとした場合だけである。
  79 .PP
  80 \fIbuf\fP に NULL が指定された場合、 \fBfmemopen\fP()  は動的に \fIsize\fP バイトの長さのバッファを確保する。
  81 この方法は、一時バッファにデータの書き込みを行ってから、 その内容を再度読み出すようなアプリケーションで有用である。
  82 このバッファはストリームがクローズされるときに自動的に解放される。 呼び出し元からはこの関数が割り当てた一時バッファへのポインタ値を
  83 知る方法は存在しない点に注意 (下記の \fBopen_memstream\fP()  も参照)。
  84
  85 \fBopen_memstream\fP()  関数は、バッファへの書き込み用にストリームをオープンする。 バッファは (\fBmalloc\fP(3)
  86 を使って) 動的に割り当てられ、必要に応じて自動的に伸長する。 ストリームをクローズした後で、呼び出し元はこのバッファを \fBfree\fP(3)
  87 すべきである。
  88
  89 このストリームが クローズ (\fBfclose\fP(3))  されたりフラッシュ (\fBfflush\fP(3))  された時に、 \fIptr\fP と
  90 \fIsizeloc\fP の値はそれぞれバッファへのポインタとそのサイズに更新される。 これらの値は、呼び出し元がそのストリームに新たな書き込みを
  91 行わない場合に限り有効である。 ストリームに書き込みを行った際には、これらの変数を参照する前に ストリームを再度フラッシュしなければならない。
  92
  93 バッファ末尾の NULL バイトは保持される。 この NULL バイトは \fIsizeloc\fP に格納されるサイズには「含まれない」。
  94
  95 ストリームのファイル位置は \fBfseek\fP(3)  や \fBfseeko\fP(3)  で変更できる。
  96 すでにデータが書き込まれた領域の末尾より先にファイル位置を動かすと、 その間の領域は 0 で埋められる。
  97
  98 \fBopen_wmemstream\fP()  は \fBopen_memstream\fP()
  99 と同様だが、バイトではなくワイド文字に対して操作を行う点が異なる。
 100 .SH 返り値
 101 成功して終了した場合には、 \fBfmemopen\fP(), \fBopen_memstream\fP(), \fBopen_wmemstream\fP()  は
 102 \fIFILE\fP ポインタを返す。 失敗した場合は、 NULL を返し、 \fIerrno\fP にエラーを示す値をセットする。
 103 .SH バージョン
 104 \fBfmemopen\fP()  と \fBopen_memstream\fP()  は glibc 1.0.x ですでに利用可能であった。
 105 \fBopen_wmemstream\fP()  は glibc 2.4 以降で利用可能である。
 106 .SH 準拠
 107 POSIX.1\-2008.  これらの関数は POSIX.1\-2001 では規定れていないが、 Linux 以外のシステムで広く利用可能である。
 108
 109 .\" http://austingroupbugs.net/view.php?id=396
 110 POSIX.1\-2008 では \fImode\fP の \(aqb\(aq は無視されるべきだと規定されて
 111 いる。一方、Technical Corrigendum (正誤表) 1 では、\fImode\fP の
 112 \(aqb\(aq が指定された場合の扱いは実装依存であることを許容するように
 113 標準規格が修正されており、glibc の \(aqb\(aq の扱いは許されている。
 114 .SH 注意
 115 これらの関数が返すファイルストリームに対応するファイル ディスクリプタはない (つまり、返されたストリームに対して \fBfileno\fP(3)
 116 を呼び出すとエラーが返ることになる)。
 117 .SH バグ
 118 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
 119 バージョン 2.7 より前の glibc では、 \fBopen_memstream\fP()
 120 で作成されたストリームの末尾より先にファイル位置を動かしても、 バッファが伸長されず、 \fBfseek\fP(3)  が失敗し \-1 が返る。
 121
 122 .\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=11216
 123 \fIsize\fP に 0 が指定された場合、 \fBfmemopen\fP() はエラー \fBEINVAL\fP で失敗
 124 する。この場合にはストリームの作成に成功して、最初の読み出しを行った際に
 125 EOF (end of file) が返される方が、ストリームの扱いの一貫性が増すだろう。
 126 また、 POSIX.1\-2008 ではこの場合のエラーは規定されていない。
 127
 128 .\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=13152
 129 \fBfmemopen\fP() に追記モード ("a" や "a+") を指定すると、
 130 ファイル位置の初期値は最初の NULL バイトに設定されるが、(ファイル
 131 オフセットをストリームの末尾以外の位置に再設定した場合)それ以降の
 132 書き込みではストリームの末尾への追記が行われる訳ではない。
 133
 134 .\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=13151
 135 \fBfmemopen\fP() の \fImode\fP 引き数に追記モード ("a" や "a+") を指定し、
 136 \fIsize\fP 引き数で指定した範囲の \fIbuf\fP 内に NULL バイトがない場合、
 137 POSIX.1\-2008 では、ファイル位置の初期値はバッファの末尾の直後の
 138 バイトに設定すべきとされている。しかし、glibc の \fBfmemopen\fP() では
 139 この場合ファイル位置は \-1 に設定される。
 140
 141 .\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=12836
 142 \fBfmemopen\fP() でバイナリモードを指定するには、
 143 \(aqb\(aq は \fImode\fP の \fI2 文字目\fP でなければならない。
 144 例えば、 "wb+" は意図通りの効果になるが、 "w+b" はそうではない。
 145 これは \fBfopen\fP(3) の \fImode\fP の扱いとは異なる。
 146
 147 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544
 148 glibc 2.9 での \fBfmemopen\fP() の「バイナリ」モードの追加は、
 149 ABI (Application Binary Interface) が黙って変更された。
 150 それ以前の \fBfmemopen\fP() では \fImode\fP 内の \(aqb\(aq は無視されていた。
 151 .SH 例
 152 このプログラムは \fBfmemopen\fP()  を使って出力バッファをオープンし、 \fBopen_memstream\fP()
 153 を使って動的にサイズが変化する出力バッファをオープンしている。 (プログラムの第一コマンドライン引き数から取った) 入力文字列を
 154 スキャンして整数を読み込み、これらの整数の二乗を出力バッファに書き出す。 このプログラムの実行例は以下のようになる。
 155 .in +4n
 156 .nf
 157
 158 $\fB ./a.out \(aq1 23 43\(aq\fP
 159 size=11; ptr=1 529 1849
 160 .fi
 161 .in
 162 .SS プログラムのソース
 163 \&
 164 .nf
 165 #define _GNU_SOURCE
 166 #include <string.h>
 167 #include <stdio.h>
 168 #include <stdlib.h>
 169
 170 #define handle_error(msg) \e
 171     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 172
 173 int
 174 main(int argc, char *argv[])
 175 {
 176     FILE *out, *in;
 177     int v, s;
 178     size_t size;
 179     char *ptr;
 180
 181     if (argc != 2) {
 182         fprintf(stderr, "Usage: %s <file>\en", argv[0]);
 183         exit(EXIT_FAILURE);
 184     }
 185
 186     in = fmemopen(argv[1], strlen(argv[1]), "r");
 187     if (in == NULL)
 188         handle_error("fmemopen");
 189
 190     out = open_memstream(&ptr, &size);
 191     if (out == NULL)
 192         handle_error("open_memstream");
 193
 194     for (;;) {
 195         s = fscanf(in, "%d", &v);
 196         if (s <= 0)
 197             break;
 198
 199         s = fprintf(out, "%d ", v * v);
 200         if (s == \-1)
 201             handle_error("fprintf");
 202     }
 203     fclose(in);
 204     fclose(out);
 205     printf("size=%ld; ptr=%s\en", (long) size, ptr);
 206     free(ptr);
 207     exit(EXIT_SUCCESS);
 208 }
 209 .fi
 210 .SH 関連項目
 211 \fBfopen\fP(3), \fBfopencookie\fP(3)
 212 .SH この文書について
 213 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 214 である。プロジェクトの説明とバグ報告に関する情報は
 215 http://www.kernel.org/doc/man\-pages/ に書かれている。