release/man3/fmemopen.3

   1 .\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de),
   2 .\" and Copyright 2005 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" Distributed under the GPL.
   4 .\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream()
   5 .\"
   6 .\" Japanese Version Copyright (c) 2005, 2006 Akihiro MOTOKI
   7 .\"                     all rights reserved.
   8 .\" Translated 2005-12-26, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
   9 .\" Updated 2006-01-20, Akihiro MOTOKI
  10 .\" Updated 2006-07-20, Akihiro MOTOKI
  11 .\" Updated 2008-11-08, Akihiro MOTOKI, LDP v3.13
  12 .\" Updated 2010-04-18, Akihiro MOTOKI, LDP v3.24
  13 .\"
  14 .TH FMEMOPEN 3 2010-09-15 "GNU" "Linux Programmer's Manual"
  15 .SH 名前
  16 fmemopen, open_memstream, open_wmemstream \-  メモリをストリームとしてオープンする
  17 .SH 書式
  18 .nf
  19 .B #include <stdio.h>
  20
  21 .BI "FILE *fmemopen(void *"buf ", size_t "size ", const char *" mode ");"
  22
  23 .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
  24
  25 .B #include <wchar.h>
  26
  27 .BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
  28 .fi
  29 .fi
  30 .sp
  31 .in -4n
  32 glibc 向けの機能検査マクロの要件
  33 .RB ( feature_test_macros (7)
  34 参照):
  35 .in
  36 .sp
  37 .BR fmemopen (),
  38 .BR open_memstream (),
  39 .BR open_wmemstream ():
  40 .PD 0
  41 .ad l
  42 .RS 4
  43 .TP 4
  44 glibc 2.10 以降:
  45 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  46 .TP
  47 glibc 2.10 より前:
  48 _GNU_SOURCE
  49 .RE
  50 .ad
  51 .PD
  52 .SH 説明
  53 .BR fmemopen ()
  54 関数は、ストリームをオープンし、そのストリームに
  55 .I mode
  56 で指定されたアクセス許可を設定する。
  57 そのストリームを通じて、
  58 .I buf
  59 で指定された文字列やメモリバッファへの読み書きができる。
  60 このバッファは少なくとも
  61 .I size
  62 バイトの長さでなければならない。
  63 .PP
  64 引き数
  65 .I mode
  66 は
  67 .BR fopen (3)
  68 の場合と同じである。
  69 .I mode
  70 で追記モード (append mode) が指定された場合、ファイル位置の初期値は
  71 バッファ中の最初の NULL バイト (\(aq\\0\(aq) の位置に設定される。
  72 それ以外の場合は、ファイル位置の初期値はバッファの先頭になる。
  73 glibc 2.9 以降では、文字 'b' を
  74 .I mode
  75 の二番目の文字として指定することができる。
  76 この文字は「バイナリ」モードを指定するものである。
  77 このモードでは、書き込み時に文字列終端のヌルバイトが黙って追加
  78 されることはない。また、
  79 .BR fseek (3)
  80 .B SEEK_END
  81 は、文字列の長さからの相対値ではなく、バッファの末尾
  82 .RI ( size
  83 で指定した値) からの相対値となる。
  84 .PP
  85 書き込み用にオープンされたストリームをフラッシュ
  86 .RB ( fflush (3))
  87 やクローズ
  88 .RB ( fclose (3))
  89 した時に、
  90 (バッファに空きがあれば) NULL バイトがバッファの末尾に書き込まれる。
  91 このようにするためには、呼び出し元は
  92 バッファに 1バイト余裕を作る
  93 .RI ( size
  94 にこの 1バイトを含めた値を指定する) 必要がある。
  95
  96 バッファに
  97 .I size
  98 バイトよりたくさん書き込もうとした場合には、エラーとなる。
  99 (デフォルトでは、このようなエラーが見えるのは
 100 .I stdio
 101 バッファがフラッシュされた時だけである。
 102 .I setbuf(fp,\ NULL)
 103 を使ってバッファリングを無効にする方法は、
 104 出力操作を行った時点でエラーを検出するのに役立つ。
 105 別の方法としては、
 106 .IR "setbuffer(fp, buf, size)"
 107 を使って、呼び出し側が明示的に
 108 stdio ストリームバッファとして
 109 .I buf
 110 を指定し、バッファの指定時にバッファのサイズを
 111 stdio に教える方法がある。)
 112 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995
 113 .\" and
 114 .\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
 115 .PP
 116 読み出し用にオープンされたストリームでは、
 117 バッファ内に NULL バイト (\(aq\\0\(aq) があっても
 118 読み出し操作がファイル末尾 (end-of-file) を返すことはない。
 119 バッファからの読み出しでファイル末尾が返るのは、
 120 ファイルポインタがバッファの先頭から
 121 .I size
 122 バイトを越えて先に進もうとした場合だけである。
 123 .PP
 124 .I buf
 125 に NULL が指定された場合、
 126 .BR fmemopen ()
 127 は動的に
 128 .I size
 129 バイトの長さのバッファを確保する。
 130 この方法は、一時バッファにデータの書き込みを行ってから、
 131 その内容を再度読み出すようなアプリケーションで有用である。
 132 このバッファはストリームがクローズされるときに自動的に解放される。
 133 呼び出し元からはこの関数が割り当てた一時バッファへのポインタ値を
 134 知る方法は存在しない点に注意 (下記の
 135 .BR open_memstream ()
 136 も参照)。
 137
 138 .BR open_memstream ()
 139 関数は、バッファへの書き込み用にストリームをオープンする。
 140 バッファは
 141 .RB ( malloc (3)
 142 を使って) 動的に割り当てられ、必要に応じて自動的に伸長する。
 143 ストリームをクローズした後で、呼び出し元はこのバッファを
 144 .BR free (3)
 145 すべきである。
 146
 147 このストリームが
 148 クローズ
 149 .RB ( fclose (3))
 150 されたりフラッシュ
 151 .RB ( fflush (3))
 152 された時に、
 153 .I ptr
 154 と
 155 .I sizeloc
 156 の値はそれぞれバッファへのポインタとそのサイズに更新される。
 157 これらの値は、呼び出し元がそのストリームに新たな書き込みを
 158 行わない場合に限り有効である。
 159 ストリームに書き込みを行った際には、これらの変数を参照する前に
 160 ストリームを再度フラッシュしなければならない。
 161
 162 バッファ末尾の NULL バイトは保持される。
 163 この NULL バイトは
 164 .I sizeloc
 165 に格納されるサイズには「含まれない」。
 166
 167 ストリームのファイル位置は
 168 .BR fseek (3)
 169 や
 170 .BR fseeko (3)
 171 で変更できる。
 172 すでにデータが書き込まれた領域の末尾より先にファイル位置を動かすと、
 173 その間の領域は 0 で埋められる。
 174
 175 .BR open_wmemstream ()
 176 は
 177 .BR open_memstream ()
 178 と同様だが、バイトではなくワイド文字に対して操作を行う点が異なる。
 179 .SH 返り値
 180 成功して終了した場合には、
 181 .BR fmemopen (),
 182 .BR open_memstream (),
 183 .BR open_wmemstream ()
 184 は
 185 .I FILE
 186 ポインタを返す。
 187 失敗した場合は、 NULL を返し、
 188 .I errno
 189 にエラーを示す値をセットする。
 190 .SH バージョン
 191 .BR fmemopen ()
 192 と
 193 .BR open_memstream ()
 194 は glibc 1.0.x ですでに利用可能であった。
 195 .BR open_wmemstream ()
 196 は glibc 2.4 以降で利用可能である。
 197 .SH 準拠
 198 POSIX.1-2008.
 199 これらの関数は POSIX.1-2001 では規定れていないが、
 200 Linux 以外のシステムで広く利用可能である。
 201 .SH 注意
 202 これらの関数が返すファイルストリームに対応するファイル
 203 ディスクリプタはない (つまり、返されたストリームに対して
 204 .BR fileno (3)
 205 を呼び出すとエラーが返ることになる)。
 206 .SH バグ
 207 バージョン 2.7 より前の glibc では、
 208 .BR open_memstream ()
 209 で作成されたストリームの末尾より先にファイル位置を動かしても、
 210 バッファが伸長されず、
 211 .BR fseek (3)
 212 が失敗し \-1 が返る。
 213 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
 214 .SH 例
 215 このプログラムは
 216 .BR fmemopen ()
 217 を使って出力バッファをオープンし、
 218 .BR open_memstream ()
 219 を使って動的にサイズが変化する出力バッファをオープンしている。
 220 (プログラムの第一コマンドライン引き数から取った) 入力文字列を
 221 スキャンして整数を読み込み、これらの整数の二乗を出力バッファに書き出す。
 222 このプログラムの実行例は以下のようになる。
 223 .in +4n
 224 .nf
 225
 226 .RB "$" " ./a.out \(aq1 23 43\(aq"
 227 size=11; ptr=1 529 1849
 228 .fi
 229 .in
 230 .SS プログラムのソース
 231 \&
 232 .nf
 233 #define _GNU_SOURCE
 234 #include <string.h>
 235 #include <stdio.h>
 236 #include <stdlib.h>
 237
 238 #define handle_error(msg) \\
 239     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 240
 241 int
 242 main(int argc, char *argv[])
 243 {
 244     FILE *out, *in;
 245     int v, s;
 246     size_t size;
 247     char *ptr;
 248
 249     if (argc != 2) {
 250         fprintf(stderr, "Usage: %s <file>\\n", argv[0]);
 251         exit(EXIT_FAILURE);
 252     }
 253
 254     in = fmemopen(argv[1], strlen(argv[1]), "r");
 255     if (in == NULL)
 256         handle_error("fmemopen");
 257
 258     out = open_memstream(&ptr, &size);
 259     if (out == NULL)
 260         handle_error("open_memstream");
 261
 262     for (;;) {
 263         s = fscanf(in, "%d", &v);
 264         if (s <= 0)
 265             break;
 266
 267         s = fprintf(out, "%d ", v * v);
 268         if (s == \-1)
 269             handle_error("fprintf");
 270     }
 271     fclose(in);
 272     fclose(out);
 273     printf("size=%ld; ptr=%s\\n", (long) size, ptr);
 274     free(ptr);
 275     exit(EXIT_SUCCESS);
 276 }
 277 .fi
 278 .SH 関連項目
 279 .BR fopen (3),
 280 .BR fopencookie (3)