Fungsi SetFilePointerEx (fileapi.h)

Artikel
01/30/2024

Memindahkan penunjuk file dari file yang ditentukan.

Sintaks

BOOL SetFilePointerEx(
  [in]            HANDLE         hFile,
  [in]            LARGE_INTEGER  liDistanceToMove,
  [out, optional] PLARGE_INTEGER lpNewFilePointer,
  [in]            DWORD          dwMoveMethod
);

Parameter

[in] hFile

Handel ke file. Handel file harus dibuat dengan hak akses GENERIC_READ atau GENERIC_WRITE . Untuk informasi selengkapnya, lihat Keamanan File dan Hak Akses.

[in] liDistanceToMove

Jumlah byte untuk memindahkan penunjuk file. Nilai positif memindahkan penunjuk ke depan dalam file dan nilai negatif memindahkan penunjuk file ke belakang.

[out, optional] lpNewFilePointer

Penunjuk ke variabel untuk menerima penunjuk file baru. Jika parameter ini NULL, penunjuk file baru tidak dikembalikan.

[in] dwMoveMethod

Titik awal untuk pemindahan penunjuk file. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
FILE_BEGIN 0	Titik awal adalah nol atau awal file. Jika bendera ini ditentukan, parameter liDistanceToMove ditafsirkan sebagai nilai yang tidak ditandatangani.
FILE_CURRENT 1	Titik awal adalah nilai pointer file saat ini.
FILE_END 2	Titik awal adalah posisi akhir file saat ini.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Penunjuk file yang dikembalikan oleh fungsi ini tidak digunakan untuk operasi baca dan tulis yang tumpang tindih. Untuk menentukan offset untuk operasi yang tumpang tindih, gunakan anggota Offset dan OffsetHigh dari struktur YANG TUMPANG TINDIH .

Anda tidak dapat menggunakan fungsi SetFilePointerEx dengan handel ke perangkat nonseeking seperti pipa atau perangkat komunikasi. Untuk menentukan jenis file untuk hFile, gunakan fungsi GetFileType .

Berhati-hatilah saat mengatur penunjuk file dalam aplikasi multithreaded. Anda harus menyinkronkan akses ke sumber daya bersama. Misalnya, aplikasi yang utasnya berbagi handel file, memperbarui penunjuk file, dan membaca dari file harus melindungi urutan ini dengan menggunakan objek bagian penting atau objek mutex. Untuk informasi selengkapnya tentang objek ini, lihat Objek Bagian Penting dan Objek Mutex.

Jika handel hFile dibuka dengan set bendera FILE_FLAG_NO_BUFFERING , aplikasi hanya dapat memindahkan penunjuk file ke posisi yang selaras dengan sektor. Posisi yang selaras dengan sektor adalah posisi yang merupakan kelipatan bilangan bulur dari ukuran sektor volume. Aplikasi dapat memperoleh ukuran sektor volume dengan memanggil fungsi GetDiskFreeSpace . Jika aplikasi memanggil SetFilePointerEx dengan nilai jarak ke pemindahan yang menghasilkan posisi yang tidak selaras dengan sektor dan handel yang dibuka dengan FILE_FLAG_NO_BUFFERING, fungsi gagal, dan GetLastError mengembalikan ERROR_INVALID_PARAMETER. Untuk informasi tambahan, lihat Buffering File.

Perhatikan bahwa ini bukan kesalahan untuk mengatur penunjuk file ke posisi di luar akhir file. Ukuran file tidak meningkat sampai Anda memanggil fungsi SetEndOfFile, WriteFile, atau WriteFileEx . Operasi tulis meningkatkan ukuran file ke posisi penunjuk file ditambah ukuran buffer yang ditulis, yang menghasilkan byte intervensi menjadi nol diinisialisasi.

Anda dapat menggunakan SetFilePointerEx untuk menentukan panjang file. Untuk melakukan ini, gunakan FILE_END untuk dwMoveMethod dan cari lokasi nol. Offset file yang dikembalikan adalah panjang file. Namun, praktik ini dapat memiliki efek samping yang tidak diinginkan, seperti kegagalan menyimpan penunjuk file saat ini sehingga program dapat kembali ke lokasi tersebut. Lebih sederhana dan lebih aman untuk menggunakan fungsi GetFileSizeEx sebagai gantinya.

Anda juga dapat menggunakan SetFilePointerEx untuk mengkueri posisi penunjuk file saat ini. Untuk melakukan ini, tentukan metode pemindahan FILE_CURRENT dan jarak nol.

Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
SMB 3.0 Transparent Failover (TFO)	Ya
SMB 3.0 dengan Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Persyaratan


Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	fileapi.h (sertakan Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll