X-Git-Url: http://git.osdn.net/view?p=linuxjm%2FLDP_man-pages.git;a=blobdiff_plain;f=draft%2Fman3%2Ffmemopen.3;h=032d8bbbe909707f1e6db779b5c8ea08a3bec60d;hp=1575f1d93ab1e71dced7d43c2ce032eccc99f4b9;hb=83f9e5d087c3464d5131604d3c9893479e6228eb;hpb=d64f6f809e331352f863bdb422001aaaaea4cbdd diff --git a/draft/man3/fmemopen.3 b/draft/man3/fmemopen.3 index 1575f1d9..032d8bbb 100644 --- a/draft/man3/fmemopen.3 +++ b/draft/man3/fmemopen.3 @@ -1,6 +1,10 @@ .\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de), -.\" and Copyright 2005 Michael Kerrisk +.\" and Copyright 2005, 2012 Michael Kerrisk +.\" +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) .\" Distributed under the GPL. +.\" %%%LICENSE_END +.\" .\" 2008-12-04, Petr Baudis : Document open_wmemstream() .\" .\"******************************************************************* @@ -8,9 +12,19 @@ .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* -.TH FMEMOPEN 3 2010\-09\-15 GNU "Linux Programmer's Manual" +.\" +.\" Japanese Version Copyright (c) 2005, 2006 Akihiro MOTOKI +.\" all rights reserved. +.\" Translated 2005-12-26, Akihiro MOTOKI +.\" Updated 2006-01-20, Akihiro MOTOKI +.\" Updated 2006-07-20, Akihiro MOTOKI +.\" Updated 2008-11-08, Akihiro MOTOKI, LDP v3.13 +.\" Updated 2010-04-18, Akihiro MOTOKI, LDP v3.24 +.\" Updated 2012-05-30, Akihiro MOTOKI +.\" +.TH FMEMOPEN 3 2015\-01\-22 GNU "Linux Programmer's Manual" .SH 名前 -fmemopen, open_memstream, open_wmemstream \- メモリをストリームとしてオープンする +fmemopen, open_memstream, open_wmemstream \- メモリーをストリームとしてオープンする .SH 書式 .nf \fB#include \fP @@ -43,47 +57,56 @@ _GNU_SOURCE .PD .SH 説明 \fBfmemopen\fP() 関数は、ストリームをオープンし、そのストリームに \fImode\fP で指定されたアクセス許可を設定する。 -そのストリームを通じて、 \fIbuf\fP で指定された文字列やメモリバッファへの読み書きができる。 このバッファは少なくとも \fIsize\fP +そのストリームを通じて、 \fIbuf\fP で指定された文字列やメモリーバッファーへの読み書きができる。 このバッファーは少なくとも \fIsize\fP バイトの長さでなければならない。 .PP -引き数 \fImode\fP は \fBfopen\fP(3) の場合と同じである。 \fImode\fP で追記モード (append mode) -が指定された場合、ファイル位置の初期値は バッファ中の最初の NULL バイト (\(aq\e0\(aq) の位置に設定される。 -それ以外の場合は、ファイル位置の初期値はバッファの先頭になる。 glibc 2.9 以降では、文字 'b' を \fImode\fP -の二番目の文字として指定することができる。 この文字は「バイナリ」モードを指定するものである。 -このモードでは、書き込み時に文字列終端のヌルバイトが黙って追加 されることはない。また、 \fBfseek\fP(3) \fBSEEK_END\fP -は、文字列の長さからの相対値ではなく、バッファの末尾 (\fIsize\fP で指定した値) からの相対値となる。 +引き数 \fImode\fP は \fBfopen\fP(3) の場合と同じである。 \fImode\fP で追記モード +(append mode) が指定された場合、ファイル位置の初期値は バッファー中の +最初のヌルバイト (\(aq\e0\(aq) の位置に設定される。 +それ以外の場合は、ファイル位置の初期値はバッファーの先頭になる。 +glibc 2.9 以降では、文字 \(aqb\(aq を \fImode\fP の二番目の文字として指定 +することができる。 この文字は「バイナリ」モードを指定するものである。 +このモードでは、書き込み時に文字列終端のヌルバイトが黙って追加 される +ことはない。また、 \fBfseek\fP(3) \fBSEEK_END\fP は、文字列の長さからの相対値 +ではなく、バッファーの末尾 (\fIsize\fP で指定した値) からの相対値となる。 .PP 書き込み用にオープンされたストリームをフラッシュ (\fBfflush\fP(3)) やクローズ (\fBfclose\fP(3)) した時に、 -(バッファに空きがあれば) NULL バイトがバッファの末尾に書き込まれる。 このようにするためには、呼び出し元は バッファに 1バイト余裕を作る +(バッファーに空きがあれば) ヌルバイトがバッファーの末尾に書き込まれる。 このようにするためには、呼び出し元は バッファーに 1バイト余裕を作る (\fIsize\fP にこの 1バイトを含めた値を指定する) 必要がある。 +バッファーに \fIsize\fP バイトよりたくさん書き込もうとした場合には、エラーとなる。 (デフォルトでは、このようなエラーが見えるのは +\fIstdio\fP バッファーがフラッシュされた時だけである。 以下の呼び出しを使ってバッファーリングを無効にする方法は、 +出力操作を行った時点でエラーを検出するのに役立つ。 + + setbuf(stdream, NULL); + +別の方法としては、 以下のように、 呼び出し側が明示的に stdio ストリームバッファーとして \fIbuf\fP +を指定し、バッファーの指定時にバッファーのサイズを stdio に教える方法がある。 + + setbuffer(stream, buf, size); + .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995 .\" and .\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html -バッファに \fIsize\fP バイトよりたくさん書き込もうとした場合には、エラーとなる。 (デフォルトでは、このようなエラーが見えるのは \fIstdio\fP -バッファがフラッシュされた時だけである。 \fIsetbuf(fp,\ NULL)\fP を使ってバッファリングを無効にする方法は、 -出力操作を行った時点でエラーを検出するのに役立つ。 別の方法としては、 \fIsetbuffer(fp, buf, size)\fP -を使って、呼び出し側が明示的に stdio ストリームバッファとして \fIbuf\fP を指定し、バッファの指定時にバッファのサイズを stdio -に教える方法がある。) .PP -読み出し用にオープンされたストリームでは、 バッファ内に NULL バイト (\(aq\e0\(aq) があっても 読み出し操作がファイル末尾 -(end\-of\-file) を返すことはない。 バッファからの読み出しでファイル末尾が返るのは、 ファイルポインタがバッファの先頭から \fIsize\fP -バイトを越えて先に進もうとした場合だけである。 +読み出し用にオープンされたストリームでは、 バッファー内にヌルバイト (\(aq\e0\(aq) があっても 読み出し操作がファイル末尾 +(end\-of\-file) を返すことはない。 バッファーからの読み出しでファイル末尾が返るのは、 ファイルポインターがバッファーの先頭から +\fIsize\fP バイトを越えて先に進もうとした場合だけである。 .PP -\fIbuf\fP に NULL が指定された場合、 \fBfmemopen\fP() は動的に \fIsize\fP バイトの長さのバッファを確保する。 -この方法は、一時バッファにデータの書き込みを行ってから、 その内容を再度読み出すようなアプリケーションで有用である。 -このバッファはストリームがクローズされるときに自動的に解放される。 呼び出し元からはこの関数が割り当てた一時バッファへのポインタ値を +\fIbuf\fP に NULL が指定された場合、 \fBfmemopen\fP() は動的に \fIsize\fP バイトの長さのバッファーを確保する。 +この方法は、一時バッファーにデータの書き込みを行ってから、 その内容を再度読み出すようなアプリケーションで有用である。 +このバッファーはストリームがクローズされるときに自動的に解放される。 呼び出し元からはこの関数が割り当てた一時バッファーへのポインター値を 知る方法は存在しない点に注意 (下記の \fBopen_memstream\fP() も参照)。 -\fBopen_memstream\fP() 関数は、バッファへの書き込み用にストリームをオープンする。 バッファは (\fBmalloc\fP(3) -を使って) 動的に割り当てられ、必要に応じて自動的に伸長する。 ストリームをクローズした後で、呼び出し元はこのバッファを \fBfree\fP(3) +\fBopen_memstream\fP() 関数は、バッファーへの書き込み用にストリームをオープンする。 バッファーは (\fBmalloc\fP(3) +を使って) 動的に割り当てられ、必要に応じて自動的に伸長する。 ストリームをクローズした後で、呼び出し元はこのバッファーを \fBfree\fP(3) すべきである。 このストリームが クローズ (\fBfclose\fP(3)) されたりフラッシュ (\fBfflush\fP(3)) された時に、 \fIptr\fP と -\fIsizeloc\fP の値はそれぞれバッファへのポインタとそのサイズに更新される。 これらの値は、呼び出し元がそのストリームに新たな書き込みを +\fIsizeloc\fP の値はそれぞれバッファーへのポインターとそのサイズに更新される。 これらの値は、呼び出し元がそのストリームに新たな書き込みを 行わない場合に限り有効である。 ストリームに書き込みを行った際には、これらの変数を参照する前に ストリームを再度フラッシュしなければならない。 -バッファ末尾の NULL バイトは保持される。 この NULL バイトは \fIsizeloc\fP に格納されるサイズには「含まれない」。 +バッファー末尾のヌルバイトは保持される。 このヌルバイトは \fIsizeloc\fP に格納されるサイズには「含まれない」。 ストリームのファイル位置は \fBfseek\fP(3) や \fBfseeko\fP(3) で変更できる。 すでにデータが書き込まれた領域の末尾より先にファイル位置を動かすと、 その間の領域は 0 で埋められる。 @@ -92,23 +115,59 @@ _GNU_SOURCE と同様だが、バイトではなくワイド文字に対して操作を行う点が異なる。 .SH 返り値 成功して終了した場合には、 \fBfmemopen\fP(), \fBopen_memstream\fP(), \fBopen_wmemstream\fP() は -\fIFILE\fP ポインタを返す。 失敗した場合は、 NULL を返し、 \fIerrno\fP にエラーを示す値をセットする。 +\fIFILE\fP ポインターを返す。 失敗した場合は、 NULL を返し、 \fIerrno\fP にエラーを示す値をセットする。 .SH バージョン \fBfmemopen\fP() と \fBopen_memstream\fP() は glibc 1.0.x ですでに利用可能であった。 \fBopen_wmemstream\fP() は glibc 2.4 以降で利用可能である。 .SH 準拠 POSIX.1\-2008. これらの関数は POSIX.1\-2001 では規定れていないが、 Linux 以外のシステムで広く利用可能である。 + +.\" http://austingroupbugs.net/view.php?id=396 +POSIX.1\-2008 では \fImode\fP の \(aqb\(aq は無視されるべきだと規定されて +いる。一方、Technical Corrigendum (正誤表) 1 では、\fImode\fP の +\(aqb\(aq が指定された場合の扱いは実装依存であることを許容するように +標準規格が修正されており、glibc の \(aqb\(aq の扱いは許されている。 .SH 注意 -これらの関数が返すファイルストリームに対応するファイル ディスクリプタはない (つまり、返されたストリームに対して \fBfileno\fP(3) +これらの関数が返すファイルストリームに対応するファイル ディスクリプターはない (つまり、返されたストリームに対して \fBfileno\fP(3) を呼び出すとエラーが返ることになる)。 .SH バグ .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996 バージョン 2.7 より前の glibc では、 \fBopen_memstream\fP() -で作成されたストリームの末尾より先にファイル位置を動かしても、 バッファが伸長されず、 \fBfseek\fP(3) が失敗し \-1 が返る。 +で作成されたストリームの末尾より先にファイル位置を動かしても、 バッファーが伸長されず、 \fBfseek\fP(3) が失敗し \-1 が返る。 + +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=11216 +\fIsize\fP に 0 が指定された場合、 \fBfmemopen\fP() はエラー \fBEINVAL\fP で失敗 +する。この場合にはストリームの作成に成功して、最初の読み出しを行った際に +EOF (end of file) が返される方が、ストリームの扱いの一貫性が増すだろう。 +また、 POSIX.1\-2008 ではこの場合のエラーは規定されていない。 + +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13152 +\fBfmemopen\fP() に追記モード ("a" や "a+") を指定すると、 +ファイル位置の初期値は最初のヌルバイトに設定されるが、(ファイル +オフセットをストリームの末尾以外の位置に再設定した場合)それ以降の +書き込みではストリームの末尾への追記が行われる訳ではない。 + +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13151 +\fBfmemopen\fP() の \fImode\fP 引き数に追記モード ("a" や "a+") を指定し、 +\fIsize\fP 引き数で指定した範囲の \fIbuf\fP 内にヌルバイトがない場合、 +POSIX.1\-2008 では、ファイル位置の初期値はバッファーの末尾の直後の +バイトに設定すべきとされている。しかし、glibc の \fBfmemopen\fP() では +この場合ファイル位置は \-1 に設定される。 + +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12836 +\fBfmemopen\fP() でバイナリモードを指定するには、 +\(aqb\(aq は \fImode\fP の \fI2 文字目\fP でなければならない。 +例えば、 "wb+" は意図通りの効果になるが、 "w+b" はそうではない。 +これは \fBfopen\fP(3) の \fImode\fP の扱いとは異なる。 + +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544 +glibc 2.9 での \fBfmemopen\fP() の「バイナリ」モードの追加は、 +ABI (Application Binary Interface) が黙って変更された。 +それ以前の \fBfmemopen\fP() では \fImode\fP 内の \(aqb\(aq は無視されていた。 .SH 例 -このプログラムは \fBfmemopen\fP() を使って出力バッファをオープンし、 \fBopen_memstream\fP() -を使って動的にサイズが変化する出力バッファをオープンしている。 (プログラムの第一コマンドライン引き数から取った) 入力文字列を -スキャンして整数を読み込み、これらの整数の二乗を出力バッファに書き出す。 このプログラムの実行例は以下のようになる。 +このプログラムは \fBfmemopen\fP() を使って出力バッファーをオープンし、 \fBopen_memstream\fP() +を使って動的にサイズが変化する出力バッファーをオープンしている。 (プログラムの第一コマンドライン引き数から取った) 入力文字列を +スキャンして整数を読み込み、これらの整数の二乗を出力バッファーに書き出す。 このプログラムの実行例は以下のようになる。 .in +4n .nf @@ -136,8 +195,8 @@ main(int argc, char *argv[]) char *ptr; if (argc != 2) { - fprintf(stderr, "Usage: %s \en", argv[0]); - exit(EXIT_FAILURE); + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); } in = fmemopen(argv[1], strlen(argv[1]), "r"); @@ -159,7 +218,7 @@ main(int argc, char *argv[]) } fclose(in); fclose(out); - printf("size=%ld; ptr=%s\en", (long) size, ptr); + printf("size=%zu; ptr=%s\en", size, ptr); free(ptr); exit(EXIT_SUCCESS); } @@ -167,6 +226,6 @@ main(int argc, char *argv[]) .SH 関連項目 \fBfopen\fP(3), \fBfopencookie\fP(3) .SH この文書について -この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部 +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man\-pages/ に書かれている。