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