リナックスコマンド

fopenのヘルプ・マニュアル

日本語 英語

• help
• man

fopen --help

man fopen

FOPEN(3) Linux Programmer’s Manual FOPEN(3) 名前 fopen, fdopen, freopen - ストリームを開く関数 書式 #include FILE *fopen(const char *path, const char *mode); FILE *fdopen(int fd, const char *mode); FILE *freopen(const char *path, const char *mode, FILE *stream); glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照): fdopen(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE 説明 fopen() 関数は、 path で指定された名前のファイルを開き、ストリームと結 びつける。 引数 mode は、以下に続く文字のひとつから始まる文字列へのポインタであ る (追加の文字がこの文字の後に続くこともある): r テキストファイルを読み出すために開く。ストリームはファイルの先頭 に位置される。 r+ 読み出しおよび書き込みするために開く。ストリームはファイルの先頭 に位置される。 w ファイルを書き込みのために開く。ファイルが既に存在する場合には長 さゼロに切り詰める。ファイルがなかった場合には新たに作成する。ス トリームはファイルの先頭に位置される。 w+ 読み出しおよび書き込みのために開く。ファイルが存在していない場合 には新たに作成する。存在している場合には長さゼロに切り詰められる 。ストリームはファイルの先頭に位置される。 a 追加 (ファイルの最後に書き込む) のために開く。ファイルが存在して いない場合には新たに作成する。ストリームはファイルの最後に位置さ れる。 a+ 読み出しおよび追加 (ファイルの最後に書き込む) のために開く。ファ イルが存在していない場合には新たに作成する。読み出しの初期ファイ ル位置はファイルの先頭であるが、書き込みは常にファイルの最後に追 加される。 mode 文字列には文字 'b' を追加指定することができ、 mode 文字列の最後 の 文 字として指定する。上記のうち 2 文字のモードの場合には 2 つの文字の間 に指定することもできる。これは C89 との互換性のためだけに用意されたもの で あり、関数の実行に対してはいかなる影響も持たない。すなわち、Linux を 含む全ての POSIX 準拠システムでは、この 'b' は無視される。 (その他の シ ス テムではテキストファイルとバイナリファイルを別々に扱うものもあるので 、もしバイナリファイルの入出力を行い、そのプログラムが非 UNIX 環境へ 移 植されると予測するなら、 'b'を付けておくのは良い考えである) mode の glibc による拡張の詳細については下記の「注意」を参照。 す べての生成されたファイルは、 S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH (0666) のモードをそのプロセスの umask 値によって修 正 したモードを持つ (umask(2) を見よ)。 読み出し/書き込みストリームに対しては任意の順序で読み書きを行うことがで きる。ただし ANSI C では、 (入力操作がファイルの末尾に到達した場合を 除 い て) 出力と入力の間にはファイルの位置決め関数を挟まなければならないこ とになっていることに注意されたい (この条件を満足しない場合には、読み 込 み 操作は、最後に書き込まれたものでなく、以前に書き込まれた値を返すこと を許されている)。したがって、このようなストリームでの読み書き操作の間に は fseek(3) または fgetpos(3) 操作を挟んでおくと良いだろう (Linux では 本当に必要となることもときどきある)。この操作は見かけ上何もしない 操 作 (no-op) でも良い (例えば fseek(..., 0L, SEEK_CUR) をその副次的効果であ る同期のためだけに呼べば良い)。 ファイルを追加モード (mode の最初の文字を a にする) で開くと、このス ト リームに対する書き込み操作は (先に fseek(stream,0,SEEK_END); の呼び出しを実行したかのように) ファイル末尾に対して行われる。 fdopen() 関数は、既存のファイル記述子 fd にストリームを結びつける。スト リームの mode ("r", "r+", "w", "w+", "a", "a+" のいずれか) はファイル記 述 子のモードと互換のものでなければならない。新しいストリームのファイル 位置指示子は fd に属している値に設定される。 error と end-of-file の 各 指示子はクリアされる。 "w" および "w+" モードでのファイルの切り詰めは行 われない。ファイル記述子の複製は行なわれない。 fdopen() で作成された ス ト リームが閉じられたときにファイル記述子も閉じられる。共有メモリのオブ ジェクトへ fdopen() を行ったときの結果は定義されていない。 freopen() 関数は path で名前が指定されたファイルを開き、 stream で指 定 さ れたストリームに、そのファイルを結びつける。もとのストリームは (もし 存在する場合には) 閉じられる。 mode 引数は fopen() 関数と同じ形で使われ る。 freopen() 関数の主な用途は、標準テキストストリーム (stderr, stdin, stdout) と対応付けられているファイルを変更することである。 返り値 fopen(), fdopen(), freopen() は成功すると FILE 型のポインタを返す。失敗 すると NULL が返され、 errno がエラーを示す値にセットされる。 エラー EINVAL fopen(), fdopen(), freopen() で与えられた mode が不適切である。 fopen(), fdopen(), freopen() 関数は malloc(3) ルーチンで規定されている エラーでも失敗することがあり、その時は対応する値に errno をセットする。 fopen() 関数は open(2) ルーチンで規定されているエラーでも失敗することが あり、その時は対応する値に errno をセットする。 fdopen() 関数は fcntl(2) ルーチンで規定されているエラーでも失敗すること があり、その時は対応する値に errno をセットする。 freopen() 関数は open(2), fclose(3), fflush(3) 各ルーチンで規定されてい るエラーでも失敗することがあり、その時は対応する値に errno をセットする 。 準拠 fopen() 関 数 と freopen() 関数は C89に準拠している。 fdopen() 関数は POSIX.1-1990 に準拠している。 注意 glibc での注意 GNU C ライブラリでは、 mode に指定できる文字列として、以下の拡張が行 わ れている: c (glibc 2.3.3 以降) open 操作、それに続く read/write 操作の、スレッドの取り消しポイ ント (cancellation points) を作成しない。 e (glibc 2.7 以降) O_CLOEXEC フラグを有効にしてファイルをオープン す る 。 詳 細 は open(2) を参照。 m (glibc 2.3 以降) I/O システムコール (read(2), write(2)) ではなく、 mmap(2) を使っ てファイルにアクセスしようとする。 mmap(2) を使おうとするのは 、 読み出し用にオープンするファイルについてだけである。 x ファイルを排他的にオープンする (open(2) の O_EXCL フラグと同様) 。ファイルがすでに存在する場合、 fopen() は失敗し 、 errno に EEXIST がセットされる。このフラグは fdopen() では無視される。 関連項目 open(2), fclose(3), fileno(3), fmemopen(3), fopencookie(3) GNU 2009-02-23 FOPEN(3)

FOPEN(3) Linux Programmer’s Manual FOPEN(3) NAME fopen, fdopen, freopen - stream open functions SYNOPSIS #include FILE *fopen(const char *path, const char *mode); FILE *fdopen(int fd, const char *mode); FILE *freopen(const char *path, const char *mode, FILE *stream); Feature Test Macro Requirements for glibc (see feature_test_macros(7)): fdopen(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE DESCRIPTION The fopen() function opens the file whose name is the string pointed to by path and associates a stream with it. The argument mode points to a string beginning with one of the follow- ing sequences (Additional characters may follow these sequences.): r Open text file for reading. The stream is positioned at the beginning of the file. r+ Open for reading and writing. The stream is positioned at the beginning of the file. w Truncate file to zero length or create text file for writing. The stream is positioned at the beginning of the file. w+ Open for reading and writing. The file is created if it does not exist, otherwise it is truncated. The stream is positioned at the beginning of the file. a Open for appending (writing at end of file). The file is cre- ated if it does not exist. The stream is positioned at the end of the file. a+ Open for reading and appending (writing at end of file). The file is created if it does not exist. The initial file position for reading is at the beginning of the file, but output is always appended to the end of the file. The mode string can also include the letter 'b' either as a last char- acter or as a character between the characters in any of the two-char- acter strings described above. This is strictly for compatibility with C89 and has no effect; the 'b' is ignored on all POSIX conforming sys- tems, including Linux. (Other systems may treat text files and binary files differently, and adding the 'b' may be a good idea if you do I/O to a binary file and expect that your program may be ported to non-Unix environments.) See NOTES below for details of glibc extensions for mode. Any created files will have mode S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH (0666), as modified by the process’s umask value (see umask(2)). Reads and writes may be intermixed on read/write streams in any order. Note that ANSI C requires that a file positioning function intervene between output and input, unless an input operation encounters end-of- file. (If this condition is not met, then a read is allowed to return the result of writes other than the most recent.) Therefore it is good practice (and indeed sometimes necessary under Linux) to put an fseek(3) or fgetpos(3) operation between write and read operations on such a stream. This operation may be an apparent no-op (as in fseek(..., 0L, SEEK_CUR) called for its synchronizing side effect. Opening a file in append mode (a as the first character of mode) causes all subsequent write operations to this stream to occur at end-of-file, as if preceded by an fseek(stream,0,SEEK_END); call. The fdopen() function associates a stream with the existing file descriptor, fd. The mode of the stream (one of the values "r", "r+", "w", "w+", "a", "a+") must be compatible with the mode of the file descriptor. The file position indicator of the new stream is set to that belonging to fd, and the error and end-of-file indicators are cleared. Modes "w" or "w+" do not cause truncation of the file. The file descriptor is not dup’ed, and will be closed when the stream cre- ated by fdopen() is closed. The result of applying fdopen() to a shared memory object is undefined. The freopen() function opens the file whose name is the string pointed to by path and associates the stream pointed to by stream with it. The original stream (if it exists) is closed. The mode argument is used just as in the fopen() function. The primary use of the freopen() function is to change the file associated with a standard text stream (stderr, stdin, or stdout). RETURN VALUE Upon successful completion fopen(), fdopen() and freopen() return a FILE pointer. Otherwise, NULL is returned and errno is set to indicate the error. ERRORS EINVAL The mode provided to fopen(), fdopen(), or freopen() was invalid. The fopen(), fdopen() and freopen() functions may also fail and set errno for any of the errors specified for the routine malloc(3). The fopen() function may also fail and set errno for any of the errors specified for the routine open(2). The fdopen() function may also fail and set errno for any of the errors specified for the routine fcntl(2). The freopen() function may also fail and set errno for any of the errors specified for the routines open(2), fclose(3) and fflush(3). CONFORMING TO The fopen() and freopen() functions conform to C89. The fdopen() func- tion conforms to POSIX.1-1990. NOTES Glibc Notes The GNU C library allows the following extensions for the string speci- fied in mode: c (since glibc 2.3.3) Do not make the open operation, or subsequent read and write operations, thread cancellation points. e (since glibc 2.7) Open the file with the O_CLOEXEC flag. See open(2) for more information. m (since glibc 2.3) Attempt to access the file using mmap(2), rather than I/O system calls (read(2), write(2)). Currently, use of mmap(2) is only attempted for a file opened for reading. x Open the file exclusively (like the O_EXCL flag of open(2)). If the file already exists, fopen() fails, and sets errno to EEX- IST. This flag is ignored for fdopen(). SEE ALSO open(2), fclose(3), fileno(3), fmemopen(3), fopencookie(3) COLOPHON This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/. GNU 2009-02-23 FOPEN(3)