[linuxjm/LDP_man-pages.git] / draft / man3 / fmemopen.3

.\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de),
.\" and Copyright 2005 Michael Kerrisk <mtk.manpages@gmail.com>
.\" Distributed under the GPL.
.\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream()
.\"
.\" Japanese Version Copyright (c) 2005, 2006 Akihiro MOTOKI
.\"                     all rights reserved.
.\" Translated 2005-12-26, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" 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
.\"
.TH FMEMOPEN 3 2010-09-15 "GNU" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O fmemopen, open_memstream, open_wmemstream \-  open memory as stream
fmemopen, open_memstream, open_wmemstream \-  メモリをストリームとしてオープンする
.\"O .SH SYNOPSIS
.SH 書式
.nf
.B #include <stdio.h>

.BI "FILE *fmemopen(void *"buf ", size_t "size ", const char *" mode ");"

.BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );

.B #include <wchar.h>

.BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
.fi
.fi
.sp
.in -4n
.\"O Feature Test Macro Requirements for glibc (see
.\"O .BR feature_test_macros (7)):
glibc 向けの機能検査マクロの要件
.RB ( feature_test_macros (7)
参照):
.in
.sp
.BR fmemopen (),
.BR open_memstream (),
.BR open_wmemstream ():
.PD 0
.ad l
.RS 4
.TP 4
.\"O Since glibc 2.10:
glibc 2.10 以降:
_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
.TP
.\"O Before glibc 2.10:
glibc 2.10 より前:
_GNU_SOURCE
.RE
.ad
.PD
.\"O .SH DESCRIPTION
.SH 説明
.\"O The
.\"O .BR fmemopen ()
.\"O function opens a stream that permits the access specified by
.\"O .IR mode .
.\"O The stream allows I/O to be performed on the string or memory buffer
.\"O pointed to by
.\"O .IR buf .
.\"O This buffer must be at least
.\"O .I size
.\"O bytes long.
.BR fmemopen ()
関数は、ストリームをオープンし、そのストリームに
.I mode
で指定されたアクセス許可を設定する。
そのストリームを通じて、
.I buf
で指定された文字列やメモリバッファへの読み書きができる。
このバッファは少なくとも
.I size
バイトの長さでなければならない。
.PP
.\"O The argument
.\"O .I mode
.\"O is the same as for
.\"O .BR fopen (3).
.\"O If
.\"O .I mode
.\"O specifies an append mode, then the initial file position is set to
.\"O the location of the first null byte (\(aq\\0\(aq) in the buffer;
.\"O otherwise the initial file position is set to the start of the buffer.
引き数
.I mode
は
.BR fopen (3)
の場合と同じである。
.I mode
で追記モード (append mode) が指定された場合、ファイル位置の初期値は
バッファ中の最初の NULL バイト (\(aq\\0\(aq) の位置に設定される。
それ以外の場合は、ファイル位置の初期値はバッファの先頭になる。
.\"O Since glibc 2.9,
.\"O the letter 'b' may be specified as the second character in
.\"O .IR mode .
.\"O This provides "binary" mode:
.\"O writes don't implicitly add a terminating null byte, and
.\"O .BR fseek (3)
.\"O .B SEEK_END
.\"O is relative to the end of the buffer (i.e., the value specified by the
.\"O .I size
.\"O argument), rather than the current string length.
glibc 2.9 以降では、文字 'b' を
.I mode
の二番目の文字として指定することができる。
この文字は「バイナリ」モードを指定するものである。
このモードでは、書き込み時に文字列終端のヌルバイトが黙って追加
されることはない。また、
.BR fseek (3)
.B SEEK_END
は、文字列の長さからの相対値ではなく、バッファの末尾
.RI ( size
で指定した値) からの相対値となる。
.PP
.\"O When a stream that has been opened for writing is flushed
.\"O .RB ( fflush (3))
.\"O or closed
.\"O .RB ( fclose (3)),
.\"O a null byte is written at the end of the buffer if there is space.
.\"O The caller should ensure that an extra byte is available in the
.\"O buffer
.\"O (and that
.\"O .I size
.\"O counts that byte)
.\"O to allow for this.
書き込み用にオープンされたストリームをフラッシュ
.RB ( fflush (3))
やクローズ
.RB ( fclose (3))
した時に、
(バッファに空きがあれば) NULL バイトがバッファの末尾に書き込まれる。
このようにするためには、呼び出し元は
バッファに 1バイト余裕を作る
.RI ( size
にこの 1バイトを含めた値を指定する) 必要がある。

.\"O Attempts to write more than
.\"O .I size
.\"O bytes to the buffer result in an error.
バッファに
.I size
バイトよりたくさん書き込もうとした場合には、エラーとなる。
.\"O (By default, such errors will only be visible when the
.\"O .I stdio
.\"O buffer is flushed.
.\"O Disabling buffering with
.\"O .I setbuf(fp,\ NULL)
.\"O may be useful to detect errors at the time of an output operation.
.\"O Alternatively, the caller can explicitly set
.\"O .I buf
.\"O as the stdio stream buffer, at the same time informing stdio
.\"O of the buffer's size, using
.\"O .IR "setbuffer(fp, buf, size)" .)
(デフォルトでは、このようなエラーが見えるのは
.I stdio
バッファがフラッシュされた時だけである。
.I setbuf(fp,\ NULL)
を使ってバッファリングを無効にする方法は、
出力操作を行った時点でエラーを検出するのに役立つ。
別の方法としては、
.IR "setbuffer(fp, buf, size)"
を使って、呼び出し側が明示的に
stdio ストリームバッファとして
.I buf
を指定し、バッファの指定時にバッファのサイズを
stdio に教える方法がある。)
.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995
.\" and
.\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
.PP
.\"O In a stream opened for reading,
.\"O null bytes (\(aq\\0\(aq) in the buffer do not cause read
.\"O operations to return an end-of-file indication.
.\"O A read from the buffer will only indicate end-of-file
.\"O when the file pointer advances
.\"O .I size
.\"O bytes past the start of the buffer.
読み出し用にオープンされたストリームでは、
バッファ内に NULL バイト (\(aq\\0\(aq) があっても
読み出し操作がファイル末尾 (end-of-file) を返すことはない。
バッファからの読み出しでファイル末尾が返るのは、
ファイルポインタがバッファの先頭から
.I size
バイトを越えて先に進もうとした場合だけである。
.PP
.\"O If
.\"O .I buf
.\"O is specified as NULL, then
.\"O .BR fmemopen ()
.\"O dynamically allocates a buffer
.\"O .I size
.\"O bytes long.
.I buf
に NULL が指定された場合、
.BR fmemopen ()
は動的に
.I size
バイトの長さのバッファを確保する。
.\"O This is useful for an application that wants to write data to
.\"O a temporary buffer and then read it back again.
.\"O The buffer is automatically freed when the stream is closed.
.\"O Note that the caller has no way to obtain a pointer to the
.\"O temporary buffer allocated by this call (but see
.\"O .BR open_memstream ()
.\"O below).
この方法は、一時バッファにデータの書き込みを行ってから、
その内容を再度読み出すようなアプリケーションで有用である。
このバッファはストリームがクローズされるときに自動的に解放される。
呼び出し元からはこの関数が割り当てた一時バッファへのポインタ値を
知る方法は存在しない点に注意 (下記の
.BR open_memstream ()
も参照)。

.\"O The
.\"O .BR open_memstream ()
.\"O function opens a stream for writing to a buffer.
.\"O The buffer
.\"O is dynamically allocated (as with
.\"O .BR malloc (3)),
.\"O and automatically grows as required.
.\"O After closing the stream, the caller should
.\"O .BR free (3)
.\"O this buffer.
.BR open_memstream ()
関数は、バッファへの書き込み用にストリームをオープンする。
バッファは
.RB ( malloc (3)
を使って) 動的に割り当てられ、必要に応じて自動的に伸長する。
ストリームをクローズした後で、呼び出し元はこのバッファを
.BR free (3)
すべきである。

.\"O When the stream is closed
.\"O .RB ( fclose (3))
.\"O or flushed
.\"O .RB ( fflush (3)),
.\"O the locations pointed to by
.\"O .I ptr
.\"O and
.\"O .I sizeloc
.\"O are updated to contain, respectively, a pointer to the buffer and the
.\"O current size of the buffer.
.\"O These values remain valid only as long as the caller
.\"O performs no further output on the stream.
.\"O If further output is performed, then the stream
.\"O must again be flushed before trying to access these variables.
このストリームが
クローズ
.RB ( fclose (3))
されたりフラッシュ
.RB ( fflush (3))
された時に、
.I ptr
と
.I sizeloc
の値はそれぞれバッファへのポインタとそのサイズに更新される。
これらの値は、呼び出し元がそのストリームに新たな書き込みを
行わない場合に限り有効である。
ストリームに書き込みを行った際には、これらの変数を参照する前に
ストリームを再度フラッシュしなければならない。

.\"O A null byte is maintained at the end of the buffer.
.\"O This byte is
.\"O .I not
.\"O included in the size value stored at
.\"O .IR sizeloc .
バッファ末尾の NULL バイトは保持される。
この NULL バイトは
.I sizeloc
に格納されるサイズには「含まれない」。

.\"O The stream's file position can be changed with
.\"O .BR fseek (3)
.\"O or
.\"O .BR fseeko (3).
.\"O Moving the file position past the end
.\"O of the data already written fills the intervening space with
.\"O zeros.
ストリームのファイル位置は
.BR fseek (3)
や
.BR fseeko (3)
で変更できる。
すでにデータが書き込まれた領域の末尾より先にファイル位置を動かすと、
その間の領域は 0 で埋められる。

.\"O The
.\"O .BR open_wmemstream ()
.\"O is similar to
.\"O .BR open_memstream (),
.\"O but operates on wide characters instead of bytes.
.BR open_wmemstream ()
は
.BR open_memstream ()
と同様だが、バイトではなくワイド文字に対して操作を行う点が異なる。
.\"O .SH "RETURN VALUE"
.SH 返り値
.\"O Upon successful completion
.\"O .BR fmemopen (),
.\"O .BR open_memstream ()
.\"O and
.\"O .BR open_wmemstream ()
.\"O return a
.\"O .I FILE
.\"O pointer.
.\"O Otherwise, NULL is returned and
.\"O .I errno
.\"O is set to indicate the error.
成功して終了した場合には、
.BR fmemopen (),
.BR open_memstream (),
.BR open_wmemstream ()
は
.I FILE
ポインタを返す。
失敗した場合は、 NULL を返し、
.I errno
にエラーを示す値をセットする。
.\"O .SH VERSIONS
.SH バージョン
.\"O .BR fmemopen ()
.\"O and
.\"O .BR open_memstream ()
.\"O were already available in glibc 1.0.x.
.\"O .BR open_wmemstream ()
.\"O is available since glibc 2.4.
.BR fmemopen ()
と
.BR open_memstream ()
は glibc 1.0.x ですでに利用可能であった。
.BR open_wmemstream ()
は glibc 2.4 以降で利用可能である。
.\"O .SH "CONFORMING TO"
.SH 準拠
POSIX.1-2008.
.\"O These functions are not specified in POSIX.1-2001,
.\"O and are not widely available on other systems.
これらの関数は POSIX.1-2001 では規定れていないが、
Linux 以外のシステムで広く利用可能である。
.\"O .SH NOTES
.SH 注意
.\"O There is no file descriptor associated with the file stream
.\"O returned by these functions
.\"O (i.e.,
.\"O .BR fileno (3)
.\"O will return an error if called on the returned stream).
これらの関数が返すファイルストリームに対応するファイル
ディスクリプタはない (つまり、返されたストリームに対して
.BR fileno (3)
を呼び出すとエラーが返ることになる)。
.\"O .SH BUGS
.SH バグ
.\"O In glibc before version 2.7, seeking past the end of a stream created by
.\"O .BR open_memstream ()
.\"O does not enlarge the buffer; instead the
.\"O .BR fseek (3)
.\"O call fails, returning \-1.
.\"O .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
バージョン 2.7 より前の glibc では、
.BR open_memstream ()
で作成されたストリームの末尾より先にファイル位置を動かしても、
バッファが伸長されず、
.BR fseek (3)
が失敗し \-1 が返る。
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
.\"O .SH "EXAMPLE"
.SH 例
.\"O The program below uses
.\"O .BR fmemopen ()
.\"O to open an input buffer, and
.\"O .BR open_memstream ()
.\"O to open a dynamically sized output buffer.
.\"O The program scans its input string (taken from the program's
.\"O first command-line argument) reading integers,
.\"O and writes the squares of these integers to the output buffer.
.\"O An example of the output produced by this program is the following:
このプログラムは
.BR fmemopen ()
を使って出力バッファをオープンし、
.BR open_memstream ()
を使って動的にサイズが変化する出力バッファをオープンしている。
(プログラムの第一コマンドライン引き数から取った) 入力文字列を
スキャンして整数を読み込み、これらの整数の二乗を出力バッファに書き出す。
このプログラムの実行例は以下のようになる。
.in +4n
.nf

.RB "$" " ./a.out \(aq1 23 43\(aq"
size=11; ptr=1 529 1849
.fi
.in
.\"O .SS Program source
.SS プログラムのソース
\&
.nf
#define _GNU_SOURCE
#include <string.h>
#include <stdio.h>
#include <stdlib.h>

#define handle_error(msg) \\
    do { perror(msg); exit(EXIT_FAILURE); } while (0)

int
main(int argc, char *argv[])
{
    FILE *out, *in;
    int v, s;
    size_t size;
    char *ptr;

    if (argc != 2) {
        fprintf(stderr, "Usage: %s <file>\\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    in = fmemopen(argv[1], strlen(argv[1]), "r");
    if (in == NULL)
        handle_error("fmemopen");

    out = open_memstream(&ptr, &size);
    if (out == NULL)
        handle_error("open_memstream");

    for (;;) {
        s = fscanf(in, "%d", &v);
        if (s <= 0)
            break;

        s = fprintf(out, "%d ", v * v);
        if (s == \-1)
            handle_error("fprintf");
    }
    fclose(in);
    fclose(out);
    printf("size=%ld; ptr=%s\\n", (long) size, ptr);
    free(ptr);
    exit(EXIT_SUCCESS);
}
.fi
.\"O .SH "SEE ALSO"
.SH 関連項目
.BR fopen (3),
.BR fopencookie (3)