_fdopen、_wfdopen

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

下位入出力用として既に開かれているファイルにストリームを関連付けます。

FILE *_fdopen(  
   int fd,
   const char *mode 
);
FILE *_wfdopen( 
   int fd,
   const wchar_t *mode 
);

パラメータ

fd
開いているファイルのファイル記述子。
mode
ファイルアクセスの種類。

戻り値

これらの各関数は、開いているストリームへのポインタを返します。エラーが発生すると、NULL のポインタ値を返します。エラーが発生した場合は、「パラメータの検証」に説明されているように、無効なパラメータハンドラが呼び出されます。実行の継続が許可された場合、errno は、無効なファイル記述子を示す EBADF に設定されるか、mode が null ポインタであったことを示す EINVAL に設定されます。

エラーコードの詳細については、「_doserrno、errno、_sys_errlist、および _sys_nerr」を参照してください。

解説

_fdopen 関数は、fd で識別されたファイルに入出力ストリームを関連付けます。このため、下位入出力用に開かれているファイルをバッファに格納したり書式設定したりできるようになります。ワイド文字列を扱う場合は、_fdopen ではなく _wfdopen を使用します。この場合、_wfdopenの mode 引数にはワイド文字列を指定します。引数の指定以外、_wfdopen と _fdopen の動作は同じです。

汎用テキストルーチンのマップ

Tchar.h のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_tfdopen	_fdopen	_fdopen	_wfdopen

mode 文字列では、ファイルの種類とファイルアクセスの方法を指定します。

mode 文字列では、次に示すように、ファイルに要求するアクセスの種類を指定します。

"r"
読み出し用に開きます。ファイルが存在しない場合や見つからない場合、fopen 呼び出しは失敗します。
"w"
書き込み用に空のファイルを開きます。指定したファイルが既に存在すると、そのファイルの内容は破棄されます。
"a"
末尾に書き込みができるようにファイルを開きます (追加モード)。ファイルが存在しない場合は、先にファイルを作成します。
"r+"
読み出しと書き込みの両方のモードで開きます。ファイルが存在している必要があります。
"w+"
読み出しと書き込みの両方のモードで空のファイルを開きます。指定したファイルが既に存在すると、そのファイルの内容は破棄されます。
"a+"
読み出しと追加の両方のモードでファイルを開きます。ファイルが存在しない場合は、先にファイルを作成します。

アクセスの種類が "a" または "a+" の場合にファイルを開くと、すべての書き込み操作はファイルの末尾から行われます。ファイルポインタは fseek または rewind を使用して移動できますが、書き込み操作の前に必ずファイルの終端に戻されます。したがって、既存のデータは上書きされません。"r+"、"w+"、または "a+" のいずれかのアクセスの種類を指定すると、読み取りと書き込みの両方を行うことができます (ファイルは "更新" モードで開きます)。ただし、読み取りと書き込みを切り替える場合は、その前に fflush、fsetpos、fseek、または rewind のいずれかの関数を実行する必要があります。必要に応じて、fsetpos 関数または fseek 関数には現在位置を指定できます。

上記の値に加え、mode に次の文字を追加すると、改行文字に変換モードを指定できます。

t
ファイルをテキスト (変換) モードで開きます。このモードでは、入力時に復帰と改行 (CR-LF: Carriage Return–Linefeed) の組み合わせが 1 つの改行 (LF: Linefeed) に変換され、出力時に LF 文字が CR-LF に変換されます。また、Ctrl + Z は入力時に EOF (EOF: end-of-file) 文字として解釈されます。読み出しおよび書き込みの両方のモードで開かれたファイルでは、fopen がファイル末尾の CTRL+Z の有無を調べ、削除できる場合は削除します。この処理が行われる理由は、Ctrl + Z で終わるファイル内を fseek 関数および ftell 関数を使用して移動すると、ファイルの終端付近で fseek が正しく動作しないことがあるためです。
b
ファイルをバイナリ (非変換) モードで開きます。上記の変換は行われません。
c
関連付けられた filename のコミットフラグを有効にして、fflush または _flushall のいずれかが呼び出された場合に、ファイルバッファの内容がディスクに直接書き込まれるようにします。
n
関連付けられた filename のコミットフラグを "コミットなし" にリセットします。これは、既定の設定です。プログラムが Commode.obj にリンクされている場合、グローバルコミットフラグもオーバーライドします。プログラムが明示的に Commode.obj にリンクされていない場合、グローバルコミットフラグの既定の設定は "コミットなし" です。
S
キャッシュがディスクからのシーケンシャルアクセスに最適化されるように指定します。ただし、シーケンシャルアクセスに限定されるわけではありません。
R
キャッシュがディスクからのランダムアクセスに最適化されるように指定します。ただし、ランダムアクセスに限定されるわけではありません。
T
ファイルを一時ファイルとして指定します。可能な場合、ファイルはディスクにフラッシュされません。
D
ファイルを一時ファイルとして指定します。最後のファイル記述子が閉じられると、ファイルは削除されます。

t、c、および n の各 mode オプションは、fopen および _fdopen の Microsoft 拡張機能です。ANSI 互換が必要な場合は使用しないでください。

t または b を mode に指定しないと、既定の変換モードは _fmode グローバル変数によって定義されます。t または b を引数の先頭に指定すると、エラーが発生して NULL が返されます。テキストモードとバイナリモードについては、「テキストモードとバイナリモードのファイル入出力」を参照してください。

fopen および _fdopen で使用される mode 文字列に有効な文字は、_open および _sopen で使用する oflag 引数に次のように対応しています。

mode 文字列の文字	_open/_sopen に相当する oflag 値
a	_O_WRONLY \| _O_APPEND (通常は _O_WRONLY \| _O_CREAT \| _O_APPEND)
a+	_O_RDWR \| _O_APPEND (通常は _O_RDWR \| _O_APPEND \| _O_CREAT )
r	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY (通常は _O_WRONLY \| _O_CREAT \| _O_TRUNC)
w+	_O_RDWR (通常は _O_RDWR \| _O_CREAT \| _O_TRUNC)
b	_O_BINARY
t	_O_TEXT
c	なし
n	なし
S	_O_SEQUENTIAL
R	_O_RANDOM
T	_O_SHORT_LIVED
D	_O_TEMPORARY

必要条件

関数	必須ヘッダー
_fdopen	<stdio.h>
_wfdopen	<stdio.h> または <wchar.h>

互換性の詳細については、「C ランタイムライブラリ」の「互換性」を参照してください。

使用例

// crt_fdopen.c
// This program opens a file using low-level
// I/O, then uses _fdopen to switch to stream
// access. It counts the lines in the file.


#include <stdlib.h>
#include <stdio.h>
#include <fcntl.h>
#include <io.h>
#include <share.h>

int main( void )
{
   FILE *stream;
   int  fd, count = 0;
   char inbuf[128];

   // Open a file.
   if( _sopen_s( &fd, "crt_fdopen.txt", _O_RDONLY, _SH_DENYNO, 0 ) )
      exit( 1 );

   // Get stream from file descriptor.
   if( (stream = _fdopen( fd, "r" )) == NULL )
      exit( 1 );

   while( fgets( inbuf, 128, stream ) != NULL )
      count++;

   // After _fdopen, close with fclose, not _close.
   fclose( stream );
   printf( "Lines in file: %d\n", count );
}