LockFileEx-Funktion (fileapi.h)

Artikel
08/23/2023

Sperrt die angegebene Datei für den exklusiven Zugriff durch den aufrufenden Prozess. Diese Funktion kann entweder synchron oder asynchron ausgeführt werden und eine exklusive oder eine gemeinsame Sperre anfordern.

Syntax

BOOL LockFileEx(
  [in]      HANDLE       hFile,
  [in]      DWORD        dwFlags,
            DWORD        dwReserved,
  [in]      DWORD        nNumberOfBytesToLockLow,
  [in]      DWORD        nNumberOfBytesToLockHigh,
  [in, out] LPOVERLAPPED lpOverlapped
);

Parameter

[in] hFile

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

[in] dwFlags

Dieser Parameter kann mindestens einer der folgenden Werte sein.

Wert	Bedeutung
LOCKFILE_EXCLUSIVE_LOCK 0x00000002	Die Funktion fordert eine exklusive Sperre an. Andernfalls wird eine freigegebene Sperre angefordert.
LOCKFILE_FAIL_IMMEDIATELY 0x00000001	Die Funktion gibt sofort zurück, wenn sie die angeforderte Sperre nicht abrufen kann. Andernfalls wird gewartet.

dwReserved

Reservierter Parameter; muss auf 0 festgelegt werden.

[in] nNumberOfBytesToLockLow

Die 32 Bit der Länge des zu sperrenden Bytebereichs in niedriger Reihenfolge.

[in] nNumberOfBytesToLockHigh

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

[in, out] lpOverlapped

Ein Zeiger auf eine ÜBERLAPPENDE Struktur, die die Funktion mit der Sperranforderung verwendet. Diese erforderliche Struktur enthält den Dateioffset des Anfangs des Sperrbereichs. Sie müssen das hEvent-Element mit einem gültigen Handle oder null initialisieren.

Rückgabewert

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

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

Hinweise

Das Sperren einer Region einer Datei wird verwendet, um mithilfe dieses Dateihandles freigegebenen oder exklusiven Zugriff auf die angegebene Region zu erhalten. Wenn das Dateihandle von einem Prozess geerbt wird, der durch den Sperrprozess erstellt wurde, wird dem untergeordneten Prozess kein Zugriff auf die gesperrte Region gewährt. Wenn der Sperrvorgang die Datei ein zweites Mal öffnet, kann er nicht über dieses zweite Handle auf die angegebene Region zugreifen, bis die Region entsperrt wird.

Das Sperren eines Teils einer Datei für den exklusiven Zugriff verweigert allen anderen Prozessen sowohl Lese- als auch Schreibzugriff auf den angegebenen Bereich der Datei. Das Sperren einer Region, die über die aktuelle Dateiendeposition hinausgeht, ist kein Fehler.

Das Sperren eines Teils einer Datei für den freigegebenen Zugriff verweigert allen Prozessen den Schreibzugriff auf den angegebenen Bereich der Datei, einschließlich des Prozesses, der die Region zuerst sperrt. Alle Prozesse können die gesperrte Region lesen.

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

Die LockFileEx-Funktion funktioniert asynchron, wenn das Dateihandle für asynchrone E/A-Vorgänge geöffnet wurde, es sei denn, das flag LOCKFILE_FAIL_IMMEDIATELY ist angegeben. Wenn eine exklusive Sperre für einen Bereich einer Datei angefordert wird, der bereits über eine freigegebene oder exklusive Sperre verfügt, gibt die Funktion den Fehler ERROR_IO_PENDING zurück. Das System signalisiert das in der OVERLAPPED-Struktur angegebene Ereignis, nachdem die Sperre gewährt wurde. Um zu bestimmen, wann die Sperre gewährt wurde, verwenden Sie die GetOverlappedResult-Funktion oder eine der Wartefunktionen. Weitere Informationen finden Sie unter Synchrone und asynchrone E/A.

Wenn das Dateihandle nicht für asynchrone E/A-Vorgänge geöffnet wurde und die Sperre nicht verfügbar ist, wartet dieser Aufruf, bis die Sperre gewährt wird oder ein Fehler auftritt, es sei denn, das flag LOCKFILE_FAIL_IMMEDIATELY ist angegeben.

Exklusive Sperren können einen vorhandenen gesperrten Bereich einer Datei nicht überlappen. Freigegebene Sperren können eine gesperrte Region überlappen, sofern für diese Region gespeicherte Sperren freigegebene Sperren sind. Eine freigegebene Sperre kann eine exklusive Sperre überlappen, wenn beide Sperren mit demselben Dateihandle erstellt wurden. Wenn eine freigegebene Sperre eine exklusive Sperre überschneidet, ist der einzige mögliche Zugriff ein Lesezugriff durch den Besitzer der Sperren. Wenn derselbe Bereich mit einer exklusiven und einer freigegebenen Sperre gesperrt ist, sind zwei Entsperrvorgänge erforderlich, um die Region zu entsperren. Der erste Entsperrvorgang entsperrt die exklusive Sperre, der zweite Entsperrvorgang die freigegebene Sperre.

Wenn ein Prozess beendet wird, wenn ein Teil einer Datei gesperrt ist 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 er beim Beenden gesperrt hat. Wenn dies nicht geschieht, 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

Anforderungen

Anforderung	Wert
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