.\" Copyright (c) 1990, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)fopen.3	8.1 (Berkeley) 6/4/93
.\" %FreeBSD: src/lib/libc/stdio/fopen.3,v 1.7.2.6 2001/12/14 18:33:57 ru Exp %
.\" $FreeBSD$
.\"
.Dd June 4, 1993
.Dt FOPEN 3
.Os
.Sh 名称
.Nm fopen ,
.Nm fdopen ,
.Nm freopen
.Nd ストリームをオープンする関数
.Sh ライブラリ
.Lb libc
.Sh 書式
.In stdio.h
.Ft FILE *
.Fn fopen "const char *path" "const char *mode"
.Ft FILE *
.Fn fdopen "int fildes" "const char *mode"
.Ft FILE *
.Fn freopen "const char *path" "const char *mode" "FILE *stream"
.Sh 解説
.Fn fopen
関数は、
.Fa path
が指す文字列の名前を持つファイルをオープンし、
それにストリームを関連付けます。
.Pp
引数
.Fa mode
は、以下のシーケンスの
1 つで始まる文字列を指します
(このシーケンスには、別のキャラクタが続いても構いません)。
.Bl -tag -width indent
.It Dq Li r
テキストファイルを読込み用にオープンします。
ストリームは、ファイルの最初に位置付けられます。
.It Dq Li r+
読込み用と書込み用にオープンします。
ストリームは、ファイルの最初に位置付けられます。
.It Dq Li w
書込み用に、ファイルを長さ 0 に切りつめるか、テキストファイルを作成します。
ストリームは、ファイルの最初に位置付けられます。
.It Dq Li w+
読込み用と書込み用にオープンします。
ファイルが存在しない場合はそのファイルが作成され、
存在する場合は切りつめられます。
ストリームは、ファイルの最初に位置付けられます。
.It Dq Li a
書込み用にオープンします。
ファイルが存在しない場合はそのファイルが作成されます。
ストリームは、ファイルの最後に位置付けられます。
それに続くファイルへの書き込みは、
.Xr fseek 3
のような操作の介在に関わりなく、
常にファイルの現時点での最後へと行われます。
.It Dq Li a+
読込み用と書込み用にオープンします。
ファイルが存在しない場合はそのファイルが作成されます。
ストリームは、ファイルの最後に位置付けられます。
それに続くファイルへの書き込みは、
.Xr fseek 3
のような操作の介在に関わりなく、
常にファイルの現時点での最後へと行われます。
.El
.Pp
.Fa mode
文字列には、3 番目の文字として、
または上で説明した 2 文字からなる文字列の間に指定する文字として、
文字 ``b'' を含めることができます。
これは
.St -isoC
との互換性を保つためのもので、効果はありません。
``b'' は無視されます。
.Pp
作成されたファイルのモードは、
.Pf \\*q Dv S_IRUSR
\&|
.Dv S_IWUSR
\&|
.Dv S_IRGRP
\&|
.Dv S_IWGRP
\&|
.Dv S_IROTH
\&|
.Dv S_IWOTH Ns \\*q
.Pq Li 0666
がプロセスの umask 値 (
.Xr umask 2
参照) で修正されたものになります。
.Pp
読み書きストリームでは、読込みと書込みをどのような順序でも
混ぜることができ、前バージョンの
.Em stdio
のように、それらの間にシーク操作は必要ありません。
しかしながら、これは他のシステムへの移植性がありません。
というのは、
.Tn ANSI C
は、入力オペレーションがファイルの終了に達していない場合、
ファイル位置付け関数が出力と入力の間に
介在することを要求しているからです。
.Pp
.Fn fdopen
関数は、既存のファイル記述子
.Fa fildes
にストリームを関連付けます。
ストリームの
.Fa mode
には、ファイル記述子のモードとの互換性が必要です。
.Xr fclose 3
によってストリームが閉じられた時には、
.Fa fildes
も閉じられます。
.Pp
.Fn freopen
関数は、
.Fa path
が指す文字列の名前が付いたファイルを開き、
.Fa stream
が指すストリームを関連付けます。
元のストリームが存在する場合、それは閉じられます。
.Fa mode
引数は、
.Fn fopen
関数と同じです。
.Fn freopen
の主な使用目的は、標準テキストストリーム
.Pf ( Em stderr, 
.Em stdin
.Em stdout )
に関連付けられたファイルを切替えることです。
.Sh 戻り値
呼び出しが成功すると、
.Fn fopen, 
.Fn fdopen, 
.Fn freopen
は
.Tn FILE
ポインタを返します。
問題がある場合は
.Dv NULL
を返し、そのエラーを示す値をグローバル変数
.Va errno
に設定します。
.Sh エラー
.Bl -tag -width Er
.It Bq Er EINVAL
.Fn fopen ,
.Fn fdopen ,
.Fn freopen
の
.Fa mode
が正しくありません。
.El
.Pp
.Fn fopen ,
.Fn fdopen ,
.Fn freopen
関数は、エラーが発生すると、ルーチン
.Xr malloc 3
で規定されたエラーを
.Va errno
に設定することもあります。
.Pp
.Fn fopen
関数は、エラーが発生すると、ルーチン
.Xr open 2
で規定されたエラーを
.Va errno
に設定することもあります。
.Pp
.Fn fdopen
関数は、エラーが発生すると、ルーチン
.Xr fcntl 2
で規定されたエラーを
.Va errno
に設定することもあります。
.Pp
.Fn freopen
関数は、エラーが発生すると、ルーチン
.Xr open 2 ,
.Xr fclose 3 ,
.Xr fflush 3
で規定されたエラーを
.Va errno
に設定することもあります。
.Sh 関連項目
.Xr open 2 ,
.Xr fclose 3 ,
.Xr fileno 3 ,
.Xr fseek 3 ,
.Xr funopen 3
.Sh 規格
.Fn fopen
関数と
.Fn freopen
関数は、
.St -isoC
に適合しています。
.Fn fdopen
関数は、
.St -p1003.1-88
に適合しています。