LockFile, fonction (fileapi.h)

Article
08/23/2023

Verrouille le fichier spécifié pour un accès exclusif par le processus appelant.

Pour spécifier des options supplémentaires, par exemple la création d’un verrou partagé ou pour une opération de blocage sur échec, utilisez la fonction LockFileEx .

Syntaxe

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

Paramètres

[in] hFile

Descripteur du fichier. Le handle de fichier doit avoir été créé avec le droit d’accès GENERIC_READ ou GENERIC_WRITE . Pour plus d’informations, consultez Sécurité des fichiers et droits d’accès.

[in] dwFileOffsetLow

32 bits d’ordre inférieur du décalage d’octet de début dans le fichier où le verrou doit commencer.

[in] dwFileOffsetHigh

32 bits d’ordre élevé du décalage d’octet de début dans le fichier où le verrou doit commencer.

[in] nNumberOfBytesToLockLow

32 bits d’ordre inférieur de la longueur de la plage d’octets à verrouiller.

[in] nNumberOfBytesToLockHigh

32 bits d’ordre élevé de la longueur de la plage d’octets à verrouiller.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro (TRUE).

Si la fonction échoue, la valeur de retour est zéro (FALSE). Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Notes

Si l’appel à LockFile se termine de manière synchrone, une entrée d’achèvement peut ne pas être mise en file d’attente lorsqu’un port d’achèvement est associé au handle de fichier.

La fonction UnlockFile déverrouille une région de fichiers verrouillée par LockFile.

Le verrouillage d’une région d’un fichier donne aux threads du processus de verrouillage un accès exclusif à la région spécifiée à l’aide de ce handle de fichier. Si le handle de fichier est hérité par un processus créé par le processus de verrouillage, le processus enfant n’a pas accès à la région verrouillée. Si le processus de verrouillage ouvre le fichier une deuxième fois, il ne peut pas accéder à la région spécifiée via ce deuxième handle tant qu’il n’a pas déverrouillé la région.

Le verrouillage d’une région d’un fichier n’empêche pas la lecture ou l’écriture à partir d’une vue de fichier mappée.

Vous pouvez verrouiller les octets qui se trouvent au-delà de la fin du fichier actif. Cela est utile pour coordonner l’ajout d’enregistrements à la fin d’un fichier.

Les verrous exclusifs ne peuvent pas chevaucher une région verrouillée existante d’un fichier. Pour plus d’informations, consultez LockFileEx.

Si LockFile ne peut pas verrouiller une région d’un fichier, il retourne zéro immédiatement. Il ne bloque pas. Pour émettre une demande de verrouillage de fichier qui sera bloquée jusqu’à ce que le verrou soit acquis, utilisez LockFileEx sans l’indicateur LOCKFILE_FAIL_IMMEDIATELY .

Si un processus se termine avec une partie d’un fichier verrouillé ou ferme un fichier dont les verrous sont en suspens, les verrous sont déverrouillés par le système d’exploitation. Toutefois, le temps nécessaire au système d’exploitation pour déverrouiller ces verrous dépend des ressources système disponibles. Par conséquent, il est recommandé que votre processus déverrouille explicitement tous les fichiers qu’il a verrouillés lorsqu’il se termine. Si ce n’est pas le cas, l’accès à ces fichiers peut être refusé si le système d’exploitation ne les a pas encore déverrouillés.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Prise en charge
Protocole Server Message Block (SMB) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Oui
Système de fichiers du volume partagé de cluster (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Exemples

Pour obtenir un exemple, consultez Ajout d’un fichier à un autre fichier.

Spécifications


Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	fileapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll