Funzione LockFile (fileapi.h)

Articolo
08/23/2023

Blocca il file specificato per l'accesso esclusivo tramite il processo chiamante.

Per specificare opzioni aggiuntive, ad esempio la creazione di un blocco condiviso o per l'operazione block-on-fail, usare la funzione LockFileEx .

Sintassi

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

Parametri

[in] hFile

Handle per il file. L'handle di file deve essere stato creato con il GENERIC_READ o GENERIC_WRITE diritto di accesso. Per altre informazioni, vedere Sicurezza file e diritti di accesso.

[in] dwFileOffsetLow

I 32 bit di ordinamento basso dell'offset di byte iniziale nel file in cui deve iniziare il blocco.

[in] dwFileOffsetHigh

I 32 bit elevati dell'offset di byte iniziale nel file in cui deve iniziare il blocco.

[in] nNumberOfBytesToLockLow

I 32 bit di bassa ordine della lunghezza dell'intervallo di byte da bloccare.

[in] nNumberOfBytesToLockHigh

L'ordine elevato di 32 bit della lunghezza dell'intervallo di byte da bloccare.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero (TRUE).

Se la funzione ha esito negativo, il valore restituito è zero (FALSE). Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Se la chiamata a LockFile viene completata in modo sincrono, una voce di completamento potrebbe non essere accodata quando una porta di completamento è associata all'handle di file.

La funzione UnlockFile sblocca un'area file bloccata da LockFile.

Il blocco di un'area di un file consente ai thread del processo di blocco l'accesso esclusivo all'area specificata usando questo handle di file. Se l'handle di file viene ereditato da un processo creato dal processo di blocco, il processo figlio non viene concesso l'accesso all'area bloccata. Se il processo di blocco apre il file una seconda volta, non può accedere all'area specificata tramite questo secondo handle finché non sblocca l'area.

Il blocco di un'area di un file non impedisce la lettura o la scrittura da una visualizzazione file mappata.

È possibile bloccare i byte che superano la fine del file corrente. Ciò è utile per coordinare l'aggiunta di record alla fine di un file.

I blocchi esclusivi non possono sovrapporsi a un'area bloccata esistente di un file. Per altre informazioni, vedere LockFileEx.

Se LockFile non riesce a bloccare un'area di un file, restituisce immediatamente zero. Non blocca. Per inviare una richiesta di blocco file che blocca fino a quando non viene acquisito il blocco, usare LockFileEx senza il flag di LOCKFILE_FAIL_IMMEDIATELY .

Se un processo termina con una parte di un file bloccato o chiude un file con blocchi in sospeso, i blocchi vengono sbloccati dal sistema operativo. Tuttavia, il tempo necessario per il sistema operativo per sbloccare questi blocchi dipende dalle risorse di sistema disponibili. È pertanto consigliabile sbloccare in modo esplicito tutti i file bloccati al termine del processo. In caso contrario, l'accesso a questi file potrebbe essere negato se il sistema operativo non li ha ancora sbloccati.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Supportato
Protocollo SMB (Server Message Block) 3.0	Sì
Failover trasparente SMB 3.0 (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
File system del volume condiviso del cluster (CsvFS)	Sì
File system resiliente (ReFS)	Sì

Esempi

Per un esempio, vedere Accodamento di un file a un altro file.

Requisiti


Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	fileapi.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll