SetFilePointerEx-Funktion (fileapi.h)

Artikel
08/23/2023

Verschiebt den Dateizeiger der angegebenen Datei.

Syntax

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

Parameter

[in] hFile

Ein Handle zur Datei. Das Dateihandle muss mit dem zugriffsrecht GENERIC_READ oder GENERIC_WRITE erstellt worden sein. Weitere Informationen finden Sie unter Dateisicherheit und Zugriffsrechte.

[in] liDistanceToMove

Die Anzahl der Bytes, die den Dateizeiger verschieben sollen. Ein positiver Wert verschiebt den Zeiger in der Datei nach vorne, und ein negativer Wert verschiebt den Dateizeiger nach hinten.

[out, optional] lpNewFilePointer

Ein Zeiger auf eine Variable, um den neuen Dateizeiger zu empfangen. Wenn dieser Parameter NULL ist, wird der neue Dateizeiger nicht zurückgegeben.

[in] dwMoveMethod

Der Startpunkt für die Dateizeigerverschiebung. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
FILE_BEGIN 0	Der Startpunkt ist 0 oder der Anfang der Datei. Wenn dieses Flag angegeben wird, wird der parameter liDistanceToMove als wert ohne Vorzeichen interpretiert.
FILE_CURRENT 1	Der Startpunkt ist der aktuelle Wert des Dateizeigers.
FILE_END 2	Der Startpunkt ist die aktuelle Position am Ende der Datei.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Der von dieser Funktion zurückgegebene Dateizeiger wird nicht für überlappende Lese- und Schreibvorgänge verwendet. Um den Offset für überlappende Vorgänge anzugeben, verwenden Sie die Elemente Offset und OffsetHigh der OVERLAPPED-Struktur .

Sie können die SetFilePointerEx-Funktion nicht mit einem Handle für ein nicht anzeigende Gerät wie eine Pipe oder ein Kommunikationsgerät verwenden. Verwenden Sie die GetFileType-Funktion, um den Dateityp für hFile zu bestimmen.

Gehen Sie vorsichtig vor, wenn Sie den Dateizeiger in einer Multithreadanwendung festlegen. Sie müssen den Zugriff auf freigegebene Ressourcen synchronisieren. Beispielsweise muss eine Anwendung, deren Threads ein Dateihandle gemeinsam nutzen, den Dateizeiger aktualisieren und aus der Datei lesen, diese Sequenz schützen, indem sie ein kritisches Abschnittsobjekt oder ein Mutex-Objekt verwendet. Weitere Informationen zu diesen Objekten finden Sie unter Kritische Abschnittsobjekte und Mutex-Objekte.

Wenn das hFile-Handle mit dem FILE_FLAG_NO_BUFFERING-Flags geöffnet wurde, kann eine Anwendung den Dateizeiger nur an sektororientierte Positionen verschieben. Eine sektororientierte Position ist eine Position, die ein ganzes Vielfaches der Branchengröße des Volumens darstellt. Eine Anwendung kann die Sektorgröße eines Volumes abrufen, indem sie die GetDiskFreeSpace-Funktion aufruft. Wenn eine Anwendung SetFilePointerEx mit Entfernungswerten aufruft, die zu einer position führen, die nicht sektorbündig ist, und einem Handle, das mit FILE_FLAG_NO_BUFFERING geöffnet wurde, schlägt die Funktion fehl, und GetLastError gibt ERROR_INVALID_PARAMETER zurück. Weitere Informationen finden Sie unter Dateipufferung.

Beachten Sie, dass es kein Fehler ist, den Dateizeiger auf eine Position außerhalb des Endes der Datei festzulegen. Die Größe der Datei wird erst erhöht, wenn Sie die Funktion SetEndOfFile, WriteFile oder WriteFileEx aufrufen. Ein Schreibvorgang erhöht die Größe der Datei auf die Dateizeigerposition und die Größe des geschriebenen Puffers, was dazu führt, dass die dazwischen liegenden Bytes 0 initialisiert werden.

Sie können SetFilePointerEx verwenden, um die Länge einer Datei zu bestimmen. Verwenden Sie dazu FILE_END für dwMoveMethod , und suchen Sie nach der Position null. Der zurückgegebene Dateioffset ist die Länge der Datei. Diese Vorgehensweise kann jedoch unbeabsichtigte Nebenwirkungen haben, z. B. fehler beim Speichern des aktuellen Dateizeigers, sodass das Programm an diesen Speicherort zurückkehren kann. Es ist einfacher und sicherer, stattdessen die GetFileSizeEx-Funktion zu verwenden.

Sie können auch SetFilePointerEx verwenden, um die aktuelle Dateizeigerposition abzufragen. Geben Sie dazu eine Move-Methode von FILE_CURRENT und einen Abstand von 0 an.

Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Unterstützt
SMB 3.0-Protokoll (Server Message Block)	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	Ja
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	fileapi.h (Einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll