LockFile-Funktion (fileapi.h)

Artikel
08/23/2023

Sperrt die angegebene Datei für den exklusiven Zugriff durch den aufrufenden Prozess.

Verwenden Sie die LockFileEx-Funktion , um zusätzliche Optionen anzugeben, z. B. das Erstellen einer freigegebenen Sperre oder für block-on-fail-Vorgänge.

Syntax

BOOL LockFile(
  [in] HANDLE hFile,
  [in] DWORD  dwFileOffsetLow,
  [in] DWORD  dwFileOffsetHigh,
  [in] DWORD  nNumberOfBytesToLockLow,
  [in] DWORD  nNumberOfBytesToLockHigh
);

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] dwFileOffsetLow

Die niedrigen 32 Bits des Anfangsbyteoffsets in der Datei, in der die Sperre beginnen soll.

[in] dwFileOffsetHigh

Die hohen 32 Bits des Anfangsbyteoffsets in der Datei, in der die Sperre beginnen soll.

[in] nNumberOfBytesToLockLow

Die niedrigen 32 Bits der Länge des zu sperrenden Bytebereichs.

[in] nNumberOfBytesToLockHigh

Die hohen 32 Bits der Länge des zu sperrenden Bytebereichs.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich null (TRUE).

Wenn die Funktion fehlschlägt, ist der Rückgabewert 0 (FALSE). Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn der Aufruf von LockFile synchron abgeschlossen wird, wird ein Abschlusseintrag möglicherweise nicht in die Warteschlange eingereiht, wenn dem Dateihandle ein Abschlussport zugeordnet ist.

Die UnlockFile-Funktion entsperrt einen durch LockFile gesperrten Dateibereich.

Durch das Sperren eines Bereichs einer Datei erhalten die Threads des Sperrprozesses exklusiven Zugriff auf die angegebene Region mithilfe dieses Dateihandles. Wenn das Dateihandle von einem Prozess geerbt wird, der vom Sperrprozess erstellt wurde, wird dem untergeordneten Prozess kein Zugriff auf die gesperrte Region gewährt. Wenn der Sperrprozess die Datei ein zweites Mal öffnet, kann sie nicht über dieses zweite Handle auf die angegebene Region zugreifen, bis die Region entsperrt wird.

Das Sperren eines Bereichs einer Datei verhindert nicht das Lesen oder Schreiben aus einer zugeordneten Dateiansicht.

Sie können Bytes sperren, die über das Ende der aktuellen Datei hinausgehen. Dies ist nützlich, um das Hinzufügen von Datensätzen am Ende einer Datei zu koordinieren.

Exklusive Sperren können einen vorhandenen gesperrten Bereich einer Datei nicht überlappen. Weitere Informationen finden Sie unter LockFileEx.

Wenn LockFile einen Bereich einer Datei nicht sperren kann, wird sofort null zurückgegeben. Es wird nicht blockiert. Wenn Sie eine Dateisperranforderung ausgeben möchten, die bis zum Abrufen der Sperre blockiert wird, verwenden Sie LockFileEx ohne das flag LOCKFILE_FAIL_IMMEDIATELY .

Wenn ein Prozess mit einem Teil einer Datei beendet wird oder eine Datei mit ausstehenden Sperren geschlossen wird, werden die Sperren vom Betriebssystem entsperrt. Die Zeit, die das Betriebssystem benötigt, um diese Sperren zu entsperren, hängt jedoch von den verfügbaren Systemressourcen ab. Daher wird empfohlen, dass Ihr Prozess alle Dateien explizit entsperrt, die beim Beenden gesperrt wurden. Wenn dies nicht der Fall ist, kann der Zugriff auf diese Dateien verweigert werden, wenn das Betriebssystem sie noch nicht entsperrt hat.

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

Beispiele

Ein Beispiel finden Sie unter Anfügen einer Datei an eine andere Datei.

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