manual/LDP_man-pages/release/man3/fopen.3

   1 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Chris Torek and the American National Standards Committee X3,
   6 .\" on Information Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)fopen.3     6.8 (Berkeley) 6/29/91
  37 .\"
  38 .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu
  39 .\" Modified, aeb, 960421, 970806
  40 .\" Modified, joey, aeb, 2002-01-03
  41 .\"
  42 .\" Japanese Version Copyright (c) 1997 YOSHINO Takashi
  43 .\"       all rights reserved.
  44 .\" Translated Thu Feb 13 12:10:38 JST 1997
  45 .\"       by YOSHINO Takashi <yoshino@civil.jcn.nihon-u.ac.jp>
  46 .\" Updated & Modified Mon Mar 1 1999
  47 .\"       by NAKANO Takeo <nakano@apm.seikei.ac.jp>
  48 .\" Updated 1999-12-08, Kentaro Shirakata <argrath@ub32.org>
  49 .\" Updated 2001-12-13, Kentaro Shirakata <argrath@ub32.org>
  50 .\" Updated 2002-03-23, Kentaro Shirakata <argrath@ub32.org>
  51 .\" Updated 2005-10-15, Kentaro Shirakata <argrath@ub32.org>
  52 .\" Updated 2006-07-20, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  53 .\"
  54 .\"WORD:        file descriptor         ファイル記述子
  55 .\"WORD:        file position indicator ファイル位置指示子
  56 .\"WORD:        indicator               指示子
  57 .\"WORD:        global variable         大域変数
  58 .\"WORD:        cancellation points     取り消しポイント
  59 .\"
  60 .TH FOPEN 3  2009-02-23 "GNU" "Linux Programmer's Manual"
  61 .SH 名前
  62 fopen, fdopen, freopen \- ストリームを開く関数
  63 .SH 書式
  64 .nf
  65 .B #include <stdio.h>
  66 .sp
  67 .BI "FILE *fopen(const char *" path ", const char *" mode );
  68
  69 .BI "FILE *fdopen(int " fd ", const char *" mode );
  70
  71 .BI "FILE *freopen(const char *" path ", const char *" mode ", FILE *" stream );
  72 .fi
  73 .sp
  74 .in -4n
  75 glibc 向けの機能検査マクロの要件
  76 .RB ( feature_test_macros (7)
  77 参照):
  78 .in
  79 .sp
  80 .BR fdopen ():
  81 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
  82 .SH 説明
  83 .BR fopen ()
  84 関数は、
  85 .I path
  86 で指定された名前のファイルを開き、ストリームと結びつける。
  87 .PP
  88 引数
  89 .I mode
  90 は、以下に続く文字のひとつから始まる文字列へのポインタである
  91 (追加の文字がこの文字の後に続くこともある):
  92 .TP
  93 .B r
  94 テキストファイルを読み出すために開く。
  95 ストリームはファイルの先頭に位置される。
  96 .TP
  97 .B r+
  98 読み出しおよび書き込みするために開く。
  99 ストリームはファイルの先頭に位置される。
 100 .TP
 101 .B w
 102 ファイルを書き込みのために開く。
 103 ファイルが既に存在する場合には長さゼロに切り詰める。
 104 ファイルがなかった場合には新たに作成する。
 105 ストリームはファイルの先頭に位置される。
 106 .TP
 107 .B w+
 108 読み出しおよび書き込みのために開く。
 109 ファイルが存在していない場合には新たに作成する。
 110 存在している場合には長さゼロに切り詰められる。
 111 ストリームはファイルの先頭に位置される。
 112 .TP
 113 .B a
 114 追加 (ファイルの最後に書き込む) のために開く。
 115 ファイルが存在していない場合には新たに作成する。
 116 ストリームはファイルの最後に位置される。
 117 .TP
 118 .B a+
 119 読み出しおよび追加 (ファイルの最後に書き込む) のために開く。
 120 ファイルが存在していない場合には新たに作成する。
 121 読み出しの初期ファイル位置はファイルの先頭であるが、
 122 書き込みは常にファイルの最後に追加される。
 123 .PP
 124 .I mode
 125 文字列には文字 \(aqb\(aq を追加指定することができ、
 126 .I mode
 127 文字列の最後の文字として指定する。
 128 上記のうち 2 文字のモードの場合には 2 つの文字の間に指定することもできる。
 129 これは C89 との互換性のためだけに用意された
 130 ものであり、関数の実行に対してはいかなる影響も持たない。
 131 すなわち、Linux を含む全ての POSIX 準拠システムでは、
 132 この \(aqb\(aq は無視される。
 133 (その他のシステムではテキストファイルとバイナリファイルを別々に扱うものもあるので、
 134 もしバイナリファイルの入出力を行い、
 135 そのプログラムが非 UNIX 環境へ移植されると予測するなら、
 136 \(aqb\(aqを付けておくのは良い考えである)
 137 .PP
 138 .I mode
 139 の glibc による拡張の詳細については下記の「注意」を参照。
 140 .PP
 141 すべての生成されたファイルは、
 142 .BR S_IRUSR " | " S_IWUSR " | "  S_IRGRP " | "  S_IWGRP " | " S_IROTH " | " S_IWOTH
 143 (0666) のモードを
 144 そのプロセスの umask 値によって修正したモードを持つ
 145 .RB ( umask (2)
 146 を見よ)。
 147 .PP
 148 読み出し/書き込みストリームに対しては任意の順序で読み書きを行うことができる。
 149 ただし ANSI C では、
 150 (入力操作がファイルの末尾に到達した場合を除いて)
 151 出力と入力の間にはファイルの位置決め関数を
 152 挟まなければならないことになっていることに注意されたい
 153 (この条件を満足しない場合には、読み込み操作は、
 154 最後に書き込まれたものでなく、以前に書き込まれた
 155 値を返すことを許されている)。
 156 したがって、このようなストリームでの読み書き操作の間には
 157 .BR fseek (3)
 158 または
 159 .BR fgetpos (3)
 160 操作を挟んでおくと良いだろう
 161 (Linux では本当に必要となることもときどきある)。
 162 この操作は見かけ上何もしない操作 (no-op) でも良い
 163 (例えば \fIfseek(..., 0L, SEEK_CUR)\fP を
 164 その副次的効果である同期のためだけに呼べば良い)。
 165 .PP
 166 ファイルを追加モード
 167 .RI ( mode
 168 の最初の文字を \fBa\fP にする) で開くと、
 169 このストリームに対する書き込み操作は (先に
 170 .nf
 171
 172     fseek(stream,0,SEEK_END);
 173
 174 .fi
 175 の呼び出しを実行したかのように) ファイル末尾に対して行われる。
 176 .PP
 177 .BR fdopen ()
 178 関数は、既存のファイル記述子
 179 .I fd
 180 にストリームを結びつける。
 181 ストリームの
 182 .I mode
 183 ("r", "r+", "w", "w+", "a", "a+" のいずれか) は
 184 ファイル記述子のモードと互換のものでなければならない。
 185 新しいストリームのファイル位置指示子は
 186 .I fd
 187 に属している値に設定される。
 188 error と end-of-file の各指示子はクリアされる。
 189 "w" および "w+" モードでのファイルの切り詰めは行われない。
 190 ファイル記述子の複製は行なわれない。
 191 .BR fdopen ()
 192 で作成されたストリームが閉じられたときにファイル記述子も
 193 閉じられる。
 194 共有メモリのオブジェクトへ
 195 .BR fdopen ()
 196 を行ったときの結果は定義されていない。
 197 .PP
 198 .BR freopen ()
 199 関数は
 200 .I path
 201 で名前が指定されたファイルを開き、
 202 .I stream
 203 で指定されたストリームに、そのファイルを結びつける。
 204 もとのストリームは (もし存在する場合には) 閉じられる。
 205 .I mode
 206 引数は
 207 .BR fopen ()
 208 関数と同じ形で使われる。
 209 .BR freopen ()
 210 関数の主な用途は、標準テキストストリーム
 211 .RI ( stderr ", " stdin ", " stdout )
 212 と対応付けられているファイルを変更することである。
 213 .SH 返り値
 214 .BR fopen (),
 215 .BR fdopen (),
 216 .BR freopen ()
 217 は成功すると
 218 .I FILE
 219 型のポインタを返す。
 220 失敗すると NULL が返され、
 221 .I errno
 222 がエラーを示す値にセットされる。
 223 .SH エラー
 224 .TP
 225 .B EINVAL
 226 .BR fopen (),
 227 .BR fdopen (),
 228 .BR freopen ()
 229 で与えられた
 230 .I mode
 231 が不適切である。
 232 .PP
 233 .BR fopen (),
 234 .BR fdopen (),
 235 .BR freopen ()
 236 関数は
 237 .BR malloc (3)
 238 ルーチンで規定されているエラーでも失敗することがあり、
 239 その時は対応する値に
 240 .I errno
 241 をセットする。
 242 .PP
 243 .BR fopen ()
 244 関数は
 245 .BR open (2)
 246 ルーチンで規定されているエラーでも失敗することがあり、
 247 その時は対応する値に
 248 .I errno
 249 をセットする。
 250 .PP
 251 .BR fdopen ()
 252 関数は
 253 .BR fcntl (2)
 254 ルーチンで規定されているエラーでも失敗することがあり、
 255 その時は対応する値に
 256 .I errno
 257 をセットする。
 258 .PP
 259 .BR freopen ()
 260 関数は
 261 .BR open (2),
 262 .BR fclose (3),
 263 .BR fflush (3)
 264 各ルーチンで規定されているエラーでも失敗することがあり、
 265 その時は対応する値に
 266 .I errno
 267 をセットする。
 268 .SH 準拠
 269 .BR fopen ()
 270 関数と
 271 .BR freopen ()
 272 関数は C89に準拠している。
 273 .BR fdopen ()
 274 関数は POSIX.1-1990 に準拠している。
 275 .SH 注意
 276 .SS glibc での注意
 277 GNU C ライブラリでは、
 278 .I mode
 279 に指定できる文字列として、以下の拡張が行われている:
 280 .TP
 281 .BR c " (glibc 2.3.3 以降)"
 282 open 操作、それに続く read/write 操作の、
 283 スレッドの取り消しポイント (cancellation points)
 284 を作成しない。
 285 .TP
 286 .BR e " (glibc 2.7 以降)"
 287 .B O_CLOEXEC
 288 フラグを有効にしてファイルをオープンする。
 289 詳細は
 290 .BR open (2)
 291 を参照。
 292 .TP
 293 .BR m " (glibc 2.3 以降)"
 294 I/O システムコール
 295 .RB ( read (2),
 296 .BR write (2))
 297 ではなく、
 298 .BR mmap (2)
 299 を使ってファイルにアクセスしようとする。
 300 .\" glibc 2.4 では
 301 .BR mmap (2)
 302 を使おうとするのは、読み出し用にオープンするファイルについてだけである。
 303 .TP
 304 .B x
 305 ファイルを排他的にオープンする
 306 .RB ( open (2)
 307 の
 308 .B O_EXCL
 309 フラグと同様)。
 310 ファイルがすでに存在する場合、
 311 .BR fopen ()
 312 は失敗し、
 313 .I errno
 314 に
 315 .B EEXIST
 316 がセットされる。
 317 このフラグは
 318 .BR fdopen ()
 319 では無視される。
 320 .\" FIXME document /,ccs= charset/
 321 .SH 関連項目
 322 .BR open (2),
 323 .BR fclose (3),
 324 .BR fileno (3),
 325 .BR fmemopen (3),
 326 .BR fopencookie (3)