.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
.\" <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
-.TH FOPENCOOKIE 3 2008\-12\-05 Linux "Linux Programmer's Manual"
+.TH FOPENCOOKIE 3 2015\-01\-22 Linux "Linux Programmer's Manual"
.SH 名前
-fopencookie \- opening a custom stream
+fopencookie \- 独自のストリームをオープンする
.SH 書式
.nf
\fB#define _GNU_SOURCE\fP /* feature_test_macros(7) 参照 */
\fB cookie_io_functions_t \fP\fIio_funcs\fP\fB);\fP
.fi
.SH 説明
-The \fBfopencookie\fP() function allows the programmer to create a custom
-implementation for a standard I/O stream. This implementation can store the
-stream's data at a location of its own choosing; for example,
-\fBfopencookie\fP() is used to implement \fBfmemopen\fP(3), which provides a
-stream interface to data that is stored in a buffer in memory.
+\fBfopencookie\fP() を使うと、 プログラマーは標準 I/O ストリームの独自の実装を作成することができる。
+この実装はストリームのデータを自分が選んだ場所に格納することができる。 例えば、 \fBfopencookie\fP() は \fBfmemopen\fP(3)
+を実装するのに使用されている。 \fBfmemopen\fP(3)
+はメモリー上のバッファーに格納されたデータに対するストリームインターフェースを提供している。
-In order to create a custom stream the programmer must:
+独自のストリームを作成するためには、 プログラマーは以下を行う必要がある。
.IP * 3
-Implement four "hook" functions that are used internally by the standard I/O
-library when performing I/O on the stream.
+ストリームに対する I/O を実行する際に標準 I/O ライブラリが内部で使用する 4 つの "フック" 関数を実装する。
.IP *
-Define a "cookie" data type, a structure that provides bookkeeping
-information (e.g., where to store data) used by the aforementioned hook
-functions. The standard I/O package knows nothing about the contents of
-this cookie (thus it is typed as \fIvoid\ *\fP when passed to
-\fBfopencookie\fP()), but automatically supplies the cookie as the first
-argument when calling the hook functions.
+"cookie" データ型を定義する。 "cookie" データ型は、上記のフック関数が使用する管理情報 (例えば、データを格納する場所など)
+を提供する構造体である。 標準の I/O パッケージにはこの cookie の内容に関する情報を持たないが (したがって
+\fBfopencookie\fP() に渡される際の型は \fIvoid\ *\fP である)、 フック関数が呼び出される際に第一引き数として cookie
+が渡される。
.IP *
-Call \fBfopencookie\fP() to open a new stream and associate the cookie and
-hook functions with that stream.
+\fBfopencookie\fP() を呼び出して、新しいストリームをオープンし、 そのストリームに cookie とフック関数を関連付ける。
.PP
-The \fBfopencookie\fP() function serves a purpose similar to \fBfopen\fP(3): it
-opens a new stream and returns a pointer to a \fIFILE\fP object that is used to
-operate on that stream.
-
-The \fIcookie\fP argument is a pointer to the caller's cookie structure that is
-to be associated with the new stream. This pointer is supplied as the first
-argument when the standard I/O library invokes any of the hook functions
-described below.
-
-The \fImode\fP argument serves the same purpose as for \fBfopen\fP(3). The
-following modes are supported: \fIr\fP, \fIw\fP, \fIa\fP, \fIr+\fP, \fIw+\fP, and \fIa+\fP.
-See \fBfopen\fP(3) for details.
-
-The \fIio_funcs\fP argument is a structure that contains four fields pointing
-to the programmer\-defined hook functions that are used to implement this
-stream. The structure is defined as follows
+\fBfopencookie\fP() 関数は \fBfopen\fP(3) と同様の機能を持つ。 新しいストリームをオープンし、
+そのストリームに対して操作を行うのに使用する \fIFILE\fP オブジェクトへのポインターを返す。
+
+\fIcookie\fP 引き数は、 新しいストリームに関連付けられる呼び出し元の cookie 構造体へのポインターである。 このポインターは、 標準
+I/O ライブラリが以下で説明するフック関数のいずれかを呼び出す際に第 1 引き数として渡される。
+
+\fImode\fP 引き数は \fBfopen\fP(3) と同じ意味を持つ。 指定できるモードは \fIr\fP, \fIw\fP, \fIa\fP, \fIr+\fP, \fIw+\fP,
+\fIa+\fP である。 詳細は \fBfopen\fP(3) を参照。
+
+\fIio_funcs\fP 引き数は、 このストリームを実装するのに使用されるプログラマーが定義した関数を指す 4 つのフィールドを持つ構造体である。
+この構造体は以下のように定義されている。
.in +4n
.nf
-struct cookie_io_functions_t {
+typedef struct {
cookie_read_function_t *read;
cookie_write_function_t *write;
cookie_seek_function_t *seek;
cookie_close_function_t *close;
-};
+} cookie_io_functions_t;
.fi
.in
-The four fields are as follows:
+4 つのフィールドの詳細は以下のとおりである。
.TP
\fIcookie_read_function_t *read\fP
-This function implements read operations for the stream. When called, it
-receives three arguments:
+この関数はストリームに対する read 操作を実装する。 呼び出される際、 3 つの引き数を受け取る。
ssize_t read(void *cookie, char *buf, size_t size);
-The \fIbuf\fP and \fIsize\fP arguments are, respectively, a buffer into which
-input data can be placed and the size of that buffer. As its function
-result, the \fIread\fP function should return the number of bytes copied into
-\fIbuf\fP, 0 on end of file, or \-1 on error. The \fIread\fP function should
-update the stream offset appropriately.
+引き数 \fIbuf\fP と \fIsize\fP は、 それぞれ、 入力データを配置できるバッファーとそのバッファーのサイズである。 関数の結果として、
+\fIread\fP 関数は \fIbuf\fP にコピーされたバイト数を、 ファイル末尾の場合は 0 を、 エラーの場合は \-1 を返す。 \fIread\fP
+関数はストリームのオフセットを適切に更新すべきである。
-If \fI*read\fP is a NULL pointer, then reads from the custom stream always
-return end of file.
+\fI*read\fP がヌルポインターの場合、 独自のストリームからの読み出しは常にファイル末尾 (end of file) を返す。
.TP
\fIcookie_write_function_t *write\fP
-This function implements write operations for the stream. When called, it
-receives three arguments:
+この関数はストリームに対する write 操作を実装する。 呼び出される際、 3 つの引き数を受け取る。
ssize_t write(void *cookie, const char *buf, size_t size);
-The \fIbuf\fP and \fIsize\fP arguments are, respectively, a buffer of data to be
-output to the stream and the size of that buffer. As its function result,
-the \fIwrite\fP function should return the number of bytes copied from \fIbuf\fP,
-or \-1 on error. The \fIwrite\fP function should update the stream offset
-appropriately.
+引き数 \fIbuf\fP と \fIsize\fP は、 それぞれ、 ストリームへの出力するデータが入ったバッファーとそのバッファーのサイズである。
+関数の結果として、 \fIwrite\fP 関数は \fIbuf\fP からコピーされたバイト数を返し、 エラーの場合は \-1 を返す。
+(この関数は負の値を返してはならない。) \fIwrite\fP 関数はストリームのオフセットを適切に更新すべきである。
-If \fI*write\fP is a NULL pointer, then output to the stream is discarded.
+\fI*write\fP がヌルポインターの場合、 このストリームへの出力は破棄される。
.TP
\fIcookie_seek_function_t *seek\fP
-This function implements seek operations on the stream. When called, it
-receives three arguments:
+この関数はストリームに対する seek 操作を実装する。 呼び出される際、 3 つの引き数を受け取る。
int seek(void *cookie, off64_t *offset, int whence);
-The \fI*offset\fP argument specifies the new file offset depending on which of
-the following three values is supplied in \fIwhence\fP:
+\fI*offset\fP 引き数は新しいファイルオフセットを指定する。 新しいオフセットは \fIwhence\fP
+に以下の値のどれが指定されたかに応じて決まる。
.RS
.TP 10
\fBSEEK_SET\fP
-The stream offset should be set \fI*offset\fP bytes from the start of the
-stream.
+ストリームオフセットを、ストリームの先頭から \fI*offset\fP バイトの位置に設定する。
.TP
\fBSEEK_CUR\fP
-\fI*offset\fP should be added to the current stream offset.
+ストリームの現在のオフセットに \fI*offset\fP を加算する。
.TP
\fBSEEK_END\fP
-The stream offset should be set to the size of the stream plus \fI*offset\fP.
+ストリームのオフセットを、ストリームのサイズに \fI*offset\fP を足した場所に設定する。
.RE
.IP
-Before returning, the \fIseek\fP function should update \fI*offset\fP to indicate
-the new stream offset.
+関数が返る前に、 \fIseek\fP 関数はストリームの新しいオフセットを示すように \fI*offset\fP を更新すべきである。
-As its function result, the \fIseek\fP function should return 0 on success, and
-\-1 on error.
+関数の結果として、 \fIseek\fP 関数は成功すると 0 を、 エラーの場合 \-1 を返す。
-If \fI*seek\fP is a NULL pointer, then it is not possible to perform seek
-operations on the stream.
+\fI*seek\fP がヌルポインターの場合、 このストリームに対して seek 操作を行うことができない。
.TP
\fIcookie_close_function_t *close\fP
-This function closes the stream. The hook function can do things such as
-freeing buffers allocated for the stream. When called, it receives one
-argument:
+この関数はストリームをクローズする。 このフック関数では、 このストリームに割り当てられたバッファーを解放するといったことができる。 呼び出される際、
+1 つの引き数を受け取る。
int close(void *cookie);
-The \fIcookie\fP argument is the cookie that the programmer supplied when
-calling \fBfopencookie\fP().
+\fIcookie\fP 引き数は \fBfopencookie\fP() の呼び出し時にプログラマーが渡した cookie である。
-As its function result, the \fIclose\fP function should return 0 on success,
-and \fBEOF\fP on error.
+関数の結果として、 \fIclose\fP 関数は成功すると 0 を、 エラーの場合 \fBEOF\fP を返す。
-If \fI*close\fP is NULL, then no special action is performed when the stream is
-closed.
+\fI*close\fP が NULL の場合、 ストリームがクローズされる際に特別な操作は何も行われない。
.SH 返り値
.\" .SH ERRORS
.\" It's not clear if errno ever gets set...
-On success \fBfopencookie\fP() returns a pointer to the new stream. On error,
-NULL is returned.
+成功すると \fBfopencookie\fP() は新しいストリームへのポインターを返す。 エラーの場合、 NULL が返される。
.SH 準拠
-This function is a nonstandard GNU extension.
+この関数は非標準の GNU 拡張である。
.SH 例
-The program below implements a custom stream whose functionality is similar
-(but not identical) to that available via \fBfmemopen\fP(3). It implements a
-stream whose data is stored in a memory buffer. The program writes its
-command\-line arguments to the stream, and then seeks through the stream
-reading two out of every five characters and writing them to standard
-output. The following shell session demonstrates the use of the program:
+以下のプログラムは、 \fBfmemopen\fP(3) で利用できるのと似た (同じではない) 機能を持つ独自のストリームを実装している。
+データがメモリーバッファーに格納されるストリームを実装している。 このプログラムは、 コマンドライン引き数をストリームに書き込み、
+それからストリームをたどって 5 文字ごとに 2 文字を読み出して、 それを標準出力に書き込む。 以下のシェルセッションはこのプログラムの使用例である。
.in +4n
.nf
.fi
.in
-Note that a more general version of the program below could be improved to
-more robustly handle various error situations (e.g., opening a stream with a
-cookie that already has an open stream; closing a stream that has already
-been closed).
+このプログラムを改良して様々なエラー状況に強くすることもできる (例えば、 オープン済みのストリームに対応する cookie
+でストリームをオープンしようとした、 すでにクローズされたストリームをクローズしようとした、など)。
.SS プログラムのソース
\&
.nf
.seek = memfile_seek,
.close = memfile_close
};
- FILE *fp;
+ FILE *stream;
struct memfile_cookie mycookie;
ssize_t nread;
long p;
mycookie.offset = 0;
mycookie.endpos = 0;
- fp = fopencookie(&mycookie,"w+", memfile_func);
- if (fp == NULL) {
+ stream = fopencookie(&mycookie,"w+", memfile_func);
+ if (stream == NULL) {
perror("fopencookie");
exit(EXIT_FAILURE);
}
/* Write command\-line arguments to our file */
for (j = 1; j < argc; j++)
- if (fputs(argv[j], fp) == EOF) {
+ if (fputs(argv[j], stream) == EOF) {
perror("fputs");
exit(EXIT_FAILURE);
}
/* Read two bytes out of every five, until EOF */
for (p = 0; ; p += 5) {
- if (fseek(fp, p, SEEK_SET) == \-1) {
+ if (fseek(stream, p, SEEK_SET) == \-1) {
perror("fseek");
exit(EXIT_FAILURE);
}
- nread = fread(buf, 1, 2, fp);
+ nread = fread(buf, 1, 2, stream);
if (nread == \-1) {
perror("fread");
exit(EXIT_FAILURE);
.fi
.SH 関連項目
\fBfclose\fP(3), \fBfmemopen\fP(3), \fBfopen\fP(3), \fBfseek\fP(3)
+.SH この文書について
+この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
+である。プロジェクトの説明とバグ報告に関する情報は
+http://www.kernel.org/doc/man\-pages/ に書かれている。
OSDN Git Service
