fsetpos() - ファイル位置の設定

標準

形式

#include <stdio.h>

int fsetpos(FILE *stream, const fpos_t *pos);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>

int fsetpos_unlocked(FILE *stream, const fpos_t *pos);

機能説明

fsetpos() 関数は、stream に関連するファイル位置を、pos で指された オブジェクトの値に応じて、ファイル内の新しい位置へ移動します。fgetpos() 関数を呼び出して pos の値を取得する 必要があります。正常終了した場合、fsetpos() 関数は、EOF 標識をクリアし、直前 の ungetc() または ungetwc() 関数の同じストリームに対する影響を 取り消します。

fsetpos() 関数の呼び出しが無効な場合、その呼び出しはフラッシュ として扱われ、ungetc 文字は廃棄されます。

fsetpos() 関数は、ワイド指向ファイルのために 2 バイト 文字セット (DBCS) 状態情報を扱います。既に存在していない位置に対する fsetpos() 関数呼び出しは、エラーになります。

テキスト・ストリームの場合、DBCS シフト状態は、パフォーマンスの問題 を含みますが、レコードの開始から再計算されます。fsetpos() 関数は、マルチバイト文字の先頭に位置を変更します。

バイナリー・ストリームの場合、DBCS シフト状態は、fsetpos() 関数に よって保管された状態に設定されます。そうするうちにレコードが更新されると、シフト状態は 誤りになります。

fsetpos() 関数呼び出しの後のストリームに対する更新モードでの次の操作 は、入力操作でも出力操作でも構いません。

マルチボリューム・データ・セットのパフォーマンス: 一般的に fgetpos() 関数および fsetpos() 関数を使用すると、位置変更のパフォーマンスが ftell() 関数および fseek() 関数と比較してよくなります (マルチボリューム・データ・セットで作業する場合)。

MVS データ・セット、VSAM データ・セット、および z/OS UNIX ファイルの大規模ファイル・サポート: fsetpos() 関数は、大規模ファイルの操作を暗黙的にサポートします。大規模ファイルでこの関数を使用するには、_LARGE_FILES フィーチャー・テスト・マクロの定義は不要です。

使用上の注意

1. ワイド指向ファイル内での位置変更や、更新の実行は、決して行わないでください。更新部分がマルチバイト・ストリングや文字の一部を上書きすると、以降のデータが無効になるのを予測すること ができなくなるためです。例えば、シフトアウト文字を上書きするデータを不注意に追加する可能性も あります。以下のデータは、シフトアウトがあることを想定していますが、初期シフト状態であるかのように扱われる場合は無効です。ファイルの終わりに位置変更したり、新規データを追加したりするのは安全です。ワイド指向ストリームの詳細については、「z/OS XL C/C++ プログラミング・ガイド」を参照してください。
2. fsetpos_unlocked() 関数は、スレッド・セーフでないことを除いて、機能的に fsetpos() 関数と 等価です。fsetpos() 関数をマルチスレッド・アプリケーション内で安全に使用できるのは、 flockfile() 関数または ftrylockfile() 関数のどちらかへの呼び出しが成功した後のように、 呼び出しスレッドが (FILE*) オブジェクトを所有している間に、この関数を呼び出す場合だけです。

戻り値

fsetpos() 関数は、ファイルの現在位置を正常に変更した場合、値 0 を戻します。

正常に実行されなかった場合、fsetpos() 関数はゼロ以外を戻し、errno を設定します。

例

/* This example opens a file called myfile.dat for reading.
   After performing input operations (not shown), it moves the file
   pointer to the beginning of the file and rereads the first byte.
 */
#include <stdio.h>

int main(void)
{

   FILE *stream;
   int retcode;
   fpos_t pos, pos1, pos2, pos3;
   char ptr[20];  /* existing file 'myfile.dat' has 20 byte records */

   /* Open file, get position of file pointer, and read first record */

   stream = fopen("myfile.dat", "rb");
   fgetpos(stream,&pos);
   pos1 = pos;
   if (!fread(ptr,sizeof(ptr),1,stream))
       printf("fread error¥n");

   /* Perform a number of read operations.  The value of 'pos'
      changes if 'pos' is passed to fgetpos()                   */
⋮
   /* Re-set pointer to start of file and re-read first record  */

   fsetpos(stream,&pos1);
   if (!fread(ptr,sizeof(ptr),1,stream))
       printf("fread error¥n");

   fclose(stream);
}

関連情報

• stdio.h
• fgetpos() - ファイル位置の取得
• ftell() - 現在のファイル位置の取得
• rewind() - ファイル位置のファイルの先頭への設定
• ungetc() - 入力ストリームへの文字のプッシュ
• ungetwc() - ストリームへのワイド文字のプッシュ