Función LockFile (fileapi.h)

Artículo
08/23/2023

Bloquea el archivo especificado para el acceso exclusivo por el proceso de llamada.

Para especificar opciones adicionales, por ejemplo, la creación de un bloqueo compartido o para la operación de bloqueo en caso de error, use la función LockFileEx .

Sintaxis

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

Parámetros

[in] hFile

Identificador del archivo. El identificador de archivo debe haberse creado con el derecho de acceso GENERIC_READ o GENERIC_WRITE . Para obtener más información, vea Seguridad de archivos y derechos de acceso.

[in] dwFileOffsetLow

El desplazamiento de bytes inicial de 32 bits de orden bajo en el archivo donde debe comenzar el bloqueo.

[in] dwFileOffsetHigh

Los 32 bits de orden superior del desplazamiento de bytes inicial en el archivo donde debe comenzar el bloqueo.

[in] nNumberOfBytesToLockLow

Los 32 bits de orden bajo de la longitud del intervalo de bytes que se van a bloquear.

[in] nNumberOfBytesToLockHigh

Los 32 bits de orden superior de la longitud del intervalo de bytes que se van a bloquear.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero (TRUE).

Si se produce un error en la función, el valor devuelto es cero (FALSE). Para obtener información de error extendida, llame a GetLastError.

Comentarios

Si la llamada a LockFile se completa de forma sincrónica, es posible que una entrada de finalización no se pone en cola cuando un puerto de finalización esté asociado al identificador de archivo.

La función UnlockFile desbloquea una región de archivo bloqueada por LockFile.

El bloqueo de una región de un archivo proporciona a los subprocesos del proceso de bloqueo acceso exclusivo a la región especificada mediante este identificador de archivo. Si un proceso creado por el proceso de bloqueo hereda el identificador de archivo, el proceso secundario no tiene acceso a la región bloqueada. Si el proceso de bloqueo abre el archivo una segunda vez, no podrá acceder a la región especificada a través de este segundo identificador hasta que desbloquee la región.

El bloqueo de una región de un archivo no impide leer o escribir desde una vista de archivo asignada.

Puede bloquear bytes que estén más allá del final del archivo actual. Esto resulta útil para coordinar la adición de registros al final de un archivo.

Los bloqueos exclusivos no se pueden superponer a una región bloqueada existente de un archivo. Para obtener más información, vea LockFileEx.

Si LockFile no puede bloquear una región de un archivo, devuelve cero inmediatamente. No bloquea. Para emitir una solicitud de bloqueo de archivo que se bloqueará hasta que se adquiera el bloqueo, use LockFileEx sin la marca LOCKFILE_FAIL_IMMEDIATELY .

Si un proceso finaliza con una parte de un archivo bloqueado o cierra un archivo que tiene bloqueos pendientes, el sistema operativo desbloquea los bloqueos. Sin embargo, el tiempo necesario para que el sistema operativo desbloquee estos bloqueos depende de los recursos del sistema disponibles. Por lo tanto, se recomienda que el proceso desbloquee explícitamente todos los archivos que ha bloqueado cuando finaliza. Si esto no se hace, es posible que se deniegue el acceso a estos archivos si el sistema operativo aún no los ha desbloqueado.

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Sí
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Sí
Sistema de archivos de Volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	Sí

Ejemplos

Para obtener un ejemplo, vea Anexar un archivo a otro archivo.

Requisitos


Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	fileapi.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll