release/man3/fopencookie.3

   1 .\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
   2 .\"      <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\"*******************************************************************
  27 .\"
  28 .\" This file was generated with po4a. Translate the source file.
  29 .\"
  30 .\"*******************************************************************
  31 .TH FOPENCOOKIE 3 2015\-01\-22 Linux "Linux Programmer's Manual"
  32 .SH 名前
  33 fopencookie \- 独自のストリームをオープンする
  34 .SH 書式
  35 .nf
  36 \fB#define _GNU_SOURCE\fP         /* feature_test_macros(7) 参照 */
  37 \fB#include <stdio.h>\fP
  38
  39 \fBFILE *fopencookie(void *\fP\fIcookie\fP\fB, const char *\fP\fImode\fP\fB,\fP
  40 \fB                  cookie_io_functions_t \fP\fIio_funcs\fP\fB);\fP
  41 .fi
  42 .SH 説明
  43 \fBfopencookie\fP() を使うと、 プログラマーは標準 I/O ストリームの独自の実装を作成することができる。
  44 この実装はストリームのデータを自分が選んだ場所に格納することができる。 例えば、 \fBfopencookie\fP() は \fBfmemopen\fP(3)
  45 を実装するのに使用されている。 \fBfmemopen\fP(3)
  46 はメモリー上のバッファーに格納されたデータに対するストリームインターフェースを提供している。
  47
  48 独自のストリームを作成するためには、 プログラマーは以下を行う必要がある。
  49 .IP * 3
  50 ストリームに対する I/O を実行する際に標準 I/O ライブラリが内部で使用する 4 つの "フック" 関数を実装する。
  51 .IP *
  52 "cookie" データ型を定義する。 "cookie" データ型は、上記のフック関数が使用する管理情報 (例えば、データを格納する場所など)
  53 を提供する構造体である。 標準の I/O パッケージにはこの cookie の内容に関する情報を持たないが (したがって
  54 \fBfopencookie\fP() に渡される際の型は \fIvoid\ *\fP である)、 フック関数が呼び出される際に第一引き数として cookie
  55 が渡される。
  56 .IP *
  57 \fBfopencookie\fP() を呼び出して、新しいストリームをオープンし、 そのストリームに cookie とフック関数を関連付ける。
  58 .PP
  59 \fBfopencookie\fP() 関数は \fBfopen\fP(3) と同様の機能を持つ。 新しいストリームをオープンし、
  60 そのストリームに対して操作を行うのに使用する \fIFILE\fP オブジェクトへのポインターを返す。
  61
  62 \fIcookie\fP 引き数は、 新しいストリームに関連付けられる呼び出し元の cookie 構造体へのポインターである。 このポインターは、 標準
  63 I/O ライブラリが以下で説明するフック関数のいずれかを呼び出す際に第 1 引き数として渡される。
  64
  65 \fImode\fP 引き数は \fBfopen\fP(3) と同じ意味を持つ。 指定できるモードは \fIr\fP, \fIw\fP, \fIa\fP, \fIr+\fP, \fIw+\fP,
  66 \fIa+\fP である。 詳細は \fBfopen\fP(3) を参照。
  67
  68 \fIio_funcs\fP 引き数は、 このストリームを実装するのに使用されるプログラマーが定義した関数を指す 4 つのフィールドを持つ構造体である。
  69 この構造体は以下のように定義されている。
  70 .in +4n
  71 .nf
  72
  73 typedef struct {
  74     cookie_read_function_t  *read;
  75     cookie_write_function_t *write;
  76     cookie_seek_function_t  *seek;
  77     cookie_close_function_t *close;
  78 } cookie_io_functions_t;
  79
  80 .fi
  81 .in
  82 4 つのフィールドの詳細は以下のとおりである。
  83 .TP
  84 \fIcookie_read_function_t *read\fP
  85 この関数はストリームに対する read 操作を実装する。 呼び出される際、 3 つの引き数を受け取る。
  86
  87     ssize_t read(void *cookie, char *buf, size_t size);
  88
  89 引き数 \fIbuf\fP と \fIsize\fP は、 それぞれ、 入力データを配置できるバッファーとそのバッファーのサイズである。 関数の結果として、
  90 \fIread\fP 関数は \fIbuf\fP にコピーされたバイト数を、 ファイル末尾の場合は 0 を、 エラーの場合は \-1 を返す。 \fIread\fP
  91 関数はストリームのオフセットを適切に更新すべきである。
  92
  93 \fI*read\fP がヌルポインターの場合、 独自のストリームからの読み出しは常にファイル末尾 (end of file) を返す。
  94 .TP
  95 \fIcookie_write_function_t *write\fP
  96 この関数はストリームに対する write 操作を実装する。 呼び出される際、 3 つの引き数を受け取る。
  97
  98     ssize_t write(void *cookie, const char *buf, size_t size);
  99
 100 引き数 \fIbuf\fP と \fIsize\fP は、 それぞれ、 ストリームへの出力するデータが入ったバッファーとそのバッファーのサイズである。
 101 関数の結果として、 \fIwrite\fP 関数は \fIbuf\fP からコピーされたバイト数を返し、 エラーの場合は \-1 を返す。
 102 (この関数は負の値を返してはならない。) \fIwrite\fP 関数はストリームのオフセットを適切に更新すべきである。
 103
 104 \fI*write\fP がヌルポインターの場合、 このストリームへの出力は破棄される。
 105 .TP
 106 \fIcookie_seek_function_t *seek\fP
 107 この関数はストリームに対する seek 操作を実装する。 呼び出される際、 3 つの引き数を受け取る。
 108
 109     int seek(void *cookie, off64_t *offset, int whence);
 110
 111 \fI*offset\fP 引き数は新しいファイルオフセットを指定する。 新しいオフセットは \fIwhence\fP
 112 に以下の値のどれが指定されたかに応じて決まる。
 113 .RS
 114 .TP  10
 115 \fBSEEK_SET\fP
 116 ストリームオフセットを、ストリームの先頭から \fI*offset\fP バイトの位置に設定する。
 117 .TP
 118 \fBSEEK_CUR\fP
 119 ストリームの現在のオフセットに \fI*offset\fP を加算する。
 120 .TP
 121 \fBSEEK_END\fP
 122 ストリームのオフセットを、ストリームのサイズに \fI*offset\fP を足した場所に設定する。
 123 .RE
 124 .IP
 125 関数が返る前に、 \fIseek\fP 関数はストリームの新しいオフセットを示すように \fI*offset\fP を更新すべきである。
 126
 127 関数の結果として、 \fIseek\fP 関数は成功すると 0 を、 エラーの場合 \-1 を返す。
 128
 129 \fI*seek\fP がヌルポインターの場合、 このストリームに対して seek 操作を行うことができない。
 130 .TP
 131 \fIcookie_close_function_t *close\fP
 132 この関数はストリームをクローズする。 このフック関数では、 このストリームに割り当てられたバッファーを解放するといったことができる。 呼び出される際、
 133 1 つの引き数を受け取る。
 134
 135     int close(void *cookie);
 136
 137 \fIcookie\fP 引き数は \fBfopencookie\fP() の呼び出し時にプログラマーが渡した cookie である。
 138
 139 関数の結果として、 \fIclose\fP 関数は成功すると 0 を、 エラーの場合 \fBEOF\fP を返す。
 140
 141 \fI*close\fP が NULL の場合、 ストリームがクローズされる際に特別な操作は何も行われない。
 142 .SH 返り値
 143 .\" .SH ERRORS
 144 .\" It's not clear if errno ever gets set...
 145 成功すると \fBfopencookie\fP() は新しいストリームへのポインターを返す。 エラーの場合、 NULL が返される。
 146 .SH 準拠
 147 この関数は非標準の GNU 拡張である。
 148 .SH 例
 149 以下のプログラムは、 \fBfmemopen\fP(3) で利用できるのと似た (同じではない) 機能を持つ独自のストリームを実装している。
 150 データがメモリーバッファーに格納されるストリームを実装している。 このプログラムは、 コマンドライン引き数をストリームに書き込み、
 151 それからストリームをたどって 5 文字ごとに 2 文字を読み出して、 それを標準出力に書き込む。 以下のシェルセッションはこのプログラムの使用例である。
 152 .in +4n
 153 .nf
 154
 155 $\fB ./a.out \(aqhello world\(aq\fP
 156 /he/
 157 / w/
 158 /d/
 159 Reached end of file
 160
 161 .fi
 162 .in
 163 このプログラムを改良して様々なエラー状況に強くすることもできる (例えば、 オープン済みのストリームに対応する cookie
 164 でストリームをオープンしようとした、 すでにクローズされたストリームをクローズしようとした、など)。
 165 .SS プログラムのソース
 166 \&
 167 .nf
 168 #define _GNU_SOURCE
 169 #include <sys/types.h>
 170 #include <stdio.h>
 171 #include <stdlib.h>
 172 #include <unistd.h>
 173 #include <string.h>
 174
 175 #define INIT_BUF_SIZE 4
 176
 177 struct memfile_cookie {
 178     char   *buf;        /* Dynamically sized buffer for data */
 179     size_t  allocated;  /* Size of buf */
 180     size_t  endpos;     /* Number of characters in buf */
 181     off_t   offset;     /* Current file offset in buf */
 182 };
 183
 184 ssize_t
 185 memfile_write(void *c, const char *buf, size_t size)
 186 {
 187     char *new_buff;
 188     struct memfile_cookie *cookie = c;
 189
 190     /* Buffer too small? Keep doubling size until big enough */
 191
 192     while (size + cookie\->offset > cookie\->allocated) {
 193         new_buff = realloc(cookie\->buf, cookie\->allocated * 2);
 194         if (new_buff == NULL) {
 195             return \-1;
 196         } else {
 197             cookie\->allocated *= 2;
 198             cookie\->buf = new_buff;
 199         }
 200     }
 201
 202     memcpy(cookie\->buf + cookie\->offset, buf, size);
 203
 204     cookie\->offset += size;
 205     if (cookie\->offset > cookie\->endpos)
 206         cookie\->endpos = cookie\->offset;
 207
 208     return size;
 209 }
 210
 211 ssize_t
 212 memfile_read(void *c, char *buf, size_t size)
 213 {
 214     ssize_t xbytes;
 215     struct memfile_cookie *cookie = c;
 216
 217     /* Fetch minimum of bytes requested and bytes available */
 218
 219     xbytes = size;
 220     if (cookie\->offset + size > cookie\->endpos)
 221         xbytes = cookie\->endpos \- cookie\->offset;
 222     if (xbytes < 0)     /* offset may be past endpos */
 223        xbytes = 0;
 224
 225     memcpy(buf, cookie\->buf + cookie\->offset, xbytes);
 226
 227     cookie\->offset += xbytes;
 228     return xbytes;
 229 }
 230
 231 int
 232 memfile_seek(void *c, off64_t *offset, int whence)
 233 {
 234     off64_t new_offset;
 235     struct memfile_cookie *cookie = c;
 236
 237     if (whence == SEEK_SET)
 238         new_offset = *offset;
 239     else if (whence == SEEK_END)
 240         new_offset = cookie\->endpos + *offset;
 241     else if (whence == SEEK_CUR)
 242         new_offset = cookie\->offset + *offset;
 243     else
 244         return \-1;
 245
 246     if (new_offset < 0)
 247         return \-1;
 248
 249     cookie\->offset = new_offset;
 250     *offset = new_offset;
 251     return 0;
 252 }
 253
 254 int
 255 memfile_close(void *c)
 256 {
 257     struct memfile_cookie *cookie = c;
 258
 259     free(cookie\->buf);
 260     cookie\->allocated = 0;
 261     cookie\->buf = NULL;
 262
 263     return 0;
 264 }
 265
 266 int
 267 main(int argc, char *argv[])
 268 {
 269     cookie_io_functions_t  memfile_func = {
 270         .read  = memfile_read,
 271         .write = memfile_write,
 272         .seek  = memfile_seek,
 273         .close = memfile_close
 274     };
 275     FILE *stream;
 276     struct memfile_cookie mycookie;
 277     ssize_t nread;
 278     long p;
 279     int j;
 280     char buf[1000];
 281
 282     /* Set up the cookie before calling fopencookie() */
 283
 284     mycookie.buf = malloc(INIT_BUF_SIZE);
 285     if (mycookie.buf == NULL) {
 286         perror("malloc");
 287         exit(EXIT_FAILURE);
 288     }
 289
 290     mycookie.allocated = INIT_BUF_SIZE;
 291     mycookie.offset = 0;
 292     mycookie.endpos = 0;
 293
 294     stream = fopencookie(&mycookie,"w+", memfile_func);
 295     if (stream == NULL) {
 296         perror("fopencookie");
 297         exit(EXIT_FAILURE);
 298     }
 299
 300     /* Write command\-line arguments to our file */
 301
 302     for (j = 1; j < argc; j++)
 303         if (fputs(argv[j], stream) == EOF) {
 304             perror("fputs");
 305             exit(EXIT_FAILURE);
 306         }
 307
 308     /* Read two bytes out of every five, until EOF */
 309
 310     for (p = 0; ; p += 5) {
 311         if (fseek(stream, p, SEEK_SET) == \-1) {
 312             perror("fseek");
 313             exit(EXIT_FAILURE);
 314         }
 315         nread = fread(buf, 1, 2, stream);
 316         if (nread == \-1) {
 317             perror("fread");
 318             exit(EXIT_FAILURE);
 319         }
 320         if (nread == 0) {
 321             printf("Reached end of file\en");
 322             break;
 323         }
 324
 325         printf("/%.*s/\en", nread, buf);
 326     }
 327
 328     exit(EXIT_SUCCESS);
 329 }
 330 .fi
 331 .SH 関連項目
 332 \fBfclose\fP(3), \fBfmemopen\fP(3), \fBfopen\fP(3), \fBfseek\fP(3)
 333 .SH この文書について
 334 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
 335 である。プロジェクトの説明とバグ報告に関する情報は
 336 http://www.kernel.org/doc/man\-pages/ に書かれている。