ungetc、ungetwc

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

更新 : 2007 年 11 月

ストリームに文字を戻します。

int ungetc(
   int c,
      FILE *stream 
);
wint_t ungetwc(
   wint_t c,
   FILE *stream 
);

パラメータ

c
戻す文字。
stream
FILE 構造体へのポインタ。

戻り値

成功した場合、これらの各関数は、c 文字引数を返します。c を戻すことができない場合または文字を読み取らなかった場合は、入力ストリームは変更されず、ungetc は EOF を返し、ungetwc は WEOF を返します。stream が NULL の場合は、「パラメータの検証」に説明されているように、無効なパラメータハンドラが呼び出されます。実行の継続が許可された場合、EOF または WEOF が返され、errno は EINVAL に設定されます。

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

解説

ungetc 関数は、文字 c を stream に戻して EOF (EOF: end-of-file) インジケータを消去します。ストリームは読み取り用に開いている必要があります。stream に対する次の読み取り操作は、c から始まります。ungetc を使用してストリームに EOF を戻す操作は無視されます。

ungetc によってストリームに戻された文字は、その文字がストリームから読み取られる前に fflush、fseek、fsetpos、または rewind を呼び出すと、消去される場合があります。ファイル位置インジケータは、文字が戻される前の値に戻ります。ストリームに対応する外部記憶領域は変更されません。テキストストリームに対する ungetc の呼び出しが成功すると、戻された文字がすべて読み取られるか破棄されるまで、ファイル位置インジケータは未指定になります。バイナリストリームに対する ungetc の呼び出しが成功するたびに、ファイル位置インジケータはデクリメントされます。呼び出し前の値が 0 だった場合は、呼び出し後の値が未定義になります。

読み取り操作またはファイル位置指定操作を行わずに ungetc を 2 回続けて呼び出すと、結果は予測できません。fscanf の呼び出し後に ungetc を呼び出すと、getc などの他の読み取り操作が実行されていない限り、その呼び出しが失敗する場合があります。これは、fscanf 自体が ungetc を呼び出すためです。

ungetwc は、ungetc のワイド文字バージョンです。ただし、テキストストリームまたはバイナリストリームに対する ungetwc の呼び出しが成功するたびに、戻された文字がすべて読み取られるか破棄されるまで、ファイル位置インジケータの値は未指定になります。

これらの関数は、スレッドセーフであり、実行中に重要情報をロックします。ロックされないバージョンについては、「_ungetc_nolock、_ungetwc_nolock」を参照してください。

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

TCHAR.H のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_ungettc	ungetc	ungetc	ungetwc

必要条件

ルーチン	必須ヘッダー
ungetc	<stdio.h>
ungetwc	<stdio.h> または <wchar.h>

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

使用例

// crt_ungetc.c
// This program first converts a character
// representation of an unsigned integer to an integer. If
// the program encounters a character that is not a digit,
// the program uses ungetc to replace it in the  stream.
//

#include <stdio.h>
#include <ctype.h>

int main( void )
{
   int ch;
   int result = 0;

   // Read in and convert number:
   while( ((ch = getchar()) != EOF) && isdigit( ch ) )
      result = result * 10 + ch - '0';    // Use digit.
   if( ch != EOF )
      ungetc( ch, stdin );                // Put nondigit back.
   printf( "Number = %d\nNext character in stream = '%c'", 
            result, getchar() );
}

521a

Number = 521
Next character in stream = 'a'